Add io page for manual

[ajhenrique]

@ajhenrique will work on this, tagging up with EMC admins to find out more.

[ajhenrique]

@KateFriedman-NOAA added permissions to access https://noaa-emc.github.io/ (thanks!), created WW3 github.io/WW3 for hosting auth repo pages/documentation as https://noaa-emc.github.io/WW3/

[ajhenrique]

io page has been added, need now to find a proper format for uploading the manual.

[edwardhartnett]

This is an old issue, but still relevant since I can't seem to find your built doxygen documentation. Is it available online anywhere?

If not, read on...

The https://noaa-emc.github.io/ are not being maintained and should not be used. This is not really the way GitHub intends the io feature to be used. We are not maintaining or updating any of the NCEPLIBS documentation there.

Instead, each project should host it's own built documentation on the gh-pages branch. This is a specially-named branch, supported by GitHub, which automatically gets pushed to the io site of that project.

For example, the NCEPLIBS-g2c project (https://github.com/NOAA-EMC/NCEPLIBS-g2c) has doxygen documentation which can be found at https://noaa-emc.github.io/NCEPLIBS-g2c/. (And a link to this documentation can be found in the README which is displayed on the project home page).

All we have to do to get our built documentation on GitHub is to create a branch called "gh-pages" which contains no code, but instead the built HTML documentation. (See the branch here: https://github.com/NOAA-EMC/NCEPLIBS-g2c/tree/gh-pages. It's not particularly readable since it is HTML output generated by Doxygen).

This supports a very simple workflow that can be done by any developer on the project:

• Do a GitHub release.
• Build the release, with documentation.
• Change the gh-pages branch to contain the contents of the html directory of the built documentation.

Now the new version of the documentation is available from the project io page. In this way, doing a release and updating the documentation happen together.

There are more complex methods available. For example, the documentation can be automatically built by GitHub every time a PR is merged, and a version of the documentation for the current develop branch will always be available.

Also we can continue to host older versions of the documentation on the gh-pages branch.

Let me know if you want to do this and I can answer questions...

[MatthewMasarik-NOAA]

@edwardhartnett , you bring up a good question. I've been working on getting all the source code marked-up and merged back to the code base in small subsets. There is a current issue for this work at #586, which also has a checklist for which files are completed. We're just under 1/3 of the way at this point. We have not started building and hosting the doxygen output yet, though. The thinking was that we wanted to have the majority, if not all, of the files marked up before hosting on github. We do plan host it as you've described using the gh-pages branch. And we would greatly appreciate being able to ask questions when we start that!

[edwardhartnett]

OK, let me know when you are ready...

[edwardhartnett]

OK, let me know when you are ready...

[MatthewMasarik-NOAA]

Will do. Thank you @edwardhartnett .

[edwardhartnett]

OK, can we add a documentation build to the existing CI now? It's OK if not all the doxygen is complete - let's get what we have built, and start iterating.

I am about to submit some documentation changes...