Add doxygen build to release process

[edwardhartnett]

The built doxygen documentation is made available on the gh-pages branch, and GitHub serves that up for us (for free!) here: https://noaa-emc.github.io/UPP/.

The documentation available on gh-pages should be the most recent release. The latest release on the UPP GitHub site is Release UPP-SRW-v2.2.0, but the documentation is for version V11.0.0.

For each release:

• Update the VERSION file.
• Generate the docs.
• Copy generated HTML docs to gh-pages branch.

I'm happy to help next time around to demonstrate.

Since there are apparently multiple maintained versions of UPP, perhaps you would like to have each of their documetation sets available on the web. Let me know and I can show you how to set that up.

[gspetro-NOAA]

Hi @edwardhartnett ,

Technically, the documentation currently available is the develop branch documentation (I'm about to update it again now that PR #965 has been merged), so the version number is misleading. However, it would be good to have the develop branch documentation available (in addition to the releases), as we do for most of our apps, but when I change the VERSION file to say "develop" instead of 11.0.0, it gives an error about the format. Do you have any suggestions?

As to having multiple maintained versions, I'd love to do that if you're willing to show me how to set that up.

Thanks, Gillian

[edwardhartnett]

Yes, we can do a develop version as well. In fact, you can have that built and updated automatically every time the develop branch changes.

Let me take a look at using a string for a VERSION...

[gspetro-NOAA]

Yes! I had been looking into doing that automatically so that we didn't need a separate gh-pages PR each time. Still planning to unless you get to it first, but probably not till after our UIFCW conference next week. If you have something that already works that you can point me to, I can maybe adjust it for UPP. As to a VERSION string, let me know what you find! :)

[edwardhartnett]

OK, I set this up for the wgrib2 repo. It works by adding a new workflow file, docs.yml, which is invoked for pushes to develop (but not PRs to develop).

The end result is that the docs on-line are updated when changes are merged to develop.

In order for this workflow to work you have to change settings (under "pages") to allow GitHub actions to update your gh-pages branch.

I have not yet figured out how to combine this with my method of showing multiple releases. If you take my docs.yml file, and replace the lines 37-55 with the UPP documentation build, it should work for you too.

[edwardhartnett]

For displaying multiple versions of the documentation I use a simple trick. When upgrading to a new version, I create a new subdirectory in the gh-pages branch, and copy all the HTML files there. Then I put something like this in my user_guide.md:

## Documentation for Previous Versions of NCEPLIBS-g2

* [NCEPLIBS-g2 Version 3.5.0](ver-3.5.0/index.html)
* [NCEPLIBS-g2 Version 3.4.9](ver-3.4.9/index.html)

This method is not compatible (I believe) with automatically updating from the develop branch. (At least, I have not figured it out yet...)

However, I believe it is more important to have documentation on-line for released versions than it is for the develop branch. The develop branch programmers are already looking at the code directly, the documentation better serves users who are not developers of the documented code, but users of it. And they will be using a released version, not the develop branch.

So until I figure out how to have both, I'm going to prefer having the versioned documentation up, including older releases, instead of the develop branch documentation. (Except in the case of wgrib2, where we are just spinning up the doxygen documentation.)

Let me know if you need help setting up either way.

[edwardhartnett]

UPP has chosen to eschew semantic versioning.

As a result, the normal methods of displaying documentation for previous releases will not work with UPP.

I will close this issue.