GitHub Pages as documentation site

[ilg-ul]

I searched for the documentation associated with the CMSIS_5 project, and I could not find it.

The expected location is the project GitHub Pages, which should be available at

http://ARM-software.github.io/CMSIS_5

and the expected content is the full CMSIS doxygen site.

For this to work, you need to create a special branch to this repo, named gh-pages; you can do this in the project Settings.

I strongly recommend to use this GitHub feature, and always publish your current documentation site here, before proceeding with the release and publishing it on your own servers.

Please notify us when the CMSIS_5 documentation pages are publicly available.

[ReinhardKeil]

This is now available under http://arm-software.github.io/CMSIS_5/General/html/index.html

[ReinhardKeil]

Note that the documentation still does not contain the RTOS2 API documentation.

[ilg-ul]

ok, great.

I suggest you also update the project settings, and set the Website to http://arm-software.github.io/CMSIS_5. (no need for /General/html/index.html, this is the result of some indirections).

And possibly refer to this URL in the README.md, so people will easily find it.

[ilg-ul]

Please note that many internal links in the documentation site are broken.

[ilg-ul]

When do you plan to update the documentation, to match the definitions in the cmsis_os2.h file? The current doxy site not only has broken links, but seems outdated.

[jkrech]

The current plan is to keep the GitHub documentation in sync with the latest release branch rather than with develop. The broken links are due to the github documentation ignoring files starting with an underbar character. Doxygen generates html-files that start with an underscore when the page identifier starts with an upper-case letter. This will be addressed in the next release so hopefully no more broken links then.

[ilg-ul]

keep the GitHub documentation in sync with the latest release branch

the usefulness of the GitHub documentation would be to help contributors understand how to use the latest features in the code.

if the documentation does not match the code, this usefulness is debatable.

The broken links are due to the github documentation ignoring files starting with an underbar character. ... upper-case letter ... This will be addressed in the next release

the CMSIS++ reference manual is also generated by Doxygen, and is published as GitHub pages without problems, so I guess there should be a solution.

the point is that if you want feedback on the new RTOSv2, you should provide up-to-date documentation with the project. don't expect contributors to generate the documentation sites locally as long as you provide only non-portable windows build scripts that cannot be used on Mac or Linux.

[ilg-ul]

since you are not using Jekyll to further process your pages, it looks like adding a .nojekyll file to the root of your site might help:

https://help.github.com/enterprise/11.10.340/user/articles/files-that-start-with-an-underscore-are-missing/

[ilg-ul]

As far as I see in the Releases section, the latest official public release is CMSIS 5.0.0 Beta 4 from May 13, and for this release there is no proper documentation available.

I don't know when you plan to make the next release, but please note that without a public and up-to-date documentation it is very difficult to get an idea on the new features of CMSIS 5.

As such, the actual DONE label associated to this issue is not accurate.

[ReinhardKeil]

We have now an updated documentation with fixed links. Of course the documentation will constantly change, but we plan to post updated versions in reasonable periods.

http://arm-software.github.io/CMSIS_5/General/html/index.html

[ilg-ul]

What is the status of the current RTOS specs? Are they stable enough to attempt a port on top of µOS++/CMSIS++? If so, when do you think a new validator will be available? (preferably as a new GitHub project).

[ilg-ul]

FYI: GitHub now has a new configuration that allows to store the documentation site in the /docs folder of master branch, without needing a separate gh-pages branch.

[ilg-ul]

Please don't forget to update the pre-built documentation site after each release.