Host doxygen html output on github pages

[MatthewMasarik-NOAA]

Pull Request Summary

Turn on doxygen html output hosting on Github Pages.

Description

• Provide a detailed description of what this PR does.
  • Doxygen html documentation is hosted on github pages via:
    • The branch gh-pages is introduced. This is the core of the PR.
    • Doxygen.in and EnableDoxygen.cmake source path updates.
    • user_guide.md was added as main page.
    • ww3_doxy_tmpl.md was removed. This was originally intended to be a reference of the minimum tags
      for each Fortran construct, to provide some consistency. It was not intended to be a part of the doxygen output documentation. Given ~2/3 of the source code has been marked-down, and there are plenty of examples in the code now to reference, it seemed like a good time for cleanup as it having already served it's purpose.
    • The URL to the hosted documentation if merged: https://NOAA-EMC.github.io/WW3.
    • Note: a "beta" version was given. This will be the case until the remaining (~1/3) of source files have been marked-down. The updates will also be manual (CI to be introduced at a later date) during the beta period. To keeps tabs on (or better yet, contribute to!) progress for the remaining source files check: Add doxygen marked-down source #586.
• Is a change of answers expected from this PR?
  • No. Only doxygen documentation related parts of the build system were changed.

Please also include the following information:

• Add any suggestions for a reviewer
  • @edwardhartnett @AlexanderRichert-NOAA
• Mention any labels that should be added: documentation, new feature.
• Are answer changes expected from this PR?
  • No.
• Co-author:
  • @edwardhartnett

Issue(s) addressed

• Please list any issues associated with this PR, including those the PR will fix/close. For example:

• fixes Add io page for manual #25
• related to Add doxygen marked-down source #586

Commit Message

Host doxygen html output on github pages

Check list

• Branch is up to date with the authoritative repository (NOAA-EMC) develop branch.
• Checked the checklist for a developer submitting to develop.
• [na] If a version number update is required, checked the updating version number checklist.
• [na] If a new feature was added, a regression test for testing the new feature is added.

Testing

• How were these changes tested?
  • By building the doxygen html documentation, verifying correctness by displaying in a browser, verifying hosting on github pages from fork. See screenshot of output displayed in browser below.
• Are the changes covered by regression tests? (If not, why? Do new tests need to be added?)
  • No testing for documentation.
• Have the matrix regression tests been run (if yes, please note HPC and compiler)?
  • N/A.
• Please indicate the expected changes in the regression test output, (Note the list of known non-identical tests.)
  • N/A.
• Please provide the summary output of matrix.comp (matrix.Diff.txt, matrixCompFull.txt and matrixCompSummary.txt):
  N/A. New homepage displayed from user_guide.md.

[MatthewMasarik-NOAA]

@edwardhartnett I listed you as a co-author from our conversations and your recommendations regarding this. please advise if you'd like anything changed

[MatthewMasarik-NOAA]

Note: all CI build checks are expected to fail for this branch, since the source code is removed.

[AlexanderRichert-NOAA]

Looks like .github/workflows/ needs to come out?

https://matthewmasarik-noaa.github.io/WW3/ looks good.

[MatthewMasarik-NOAA]

Looks like .github/workflows/ needs to come out?

Ah! Thanks @AlexanderRichert-NOAA. I'll make that update.

[MatthewMasarik-NOAA]

Workflows are removed, so now no failed CI.

[MatthewMasarik-NOAA]

Processing paused: Temporary PR Policy.

[JessicaMeixner-NOAA]

@MatthewMasarik-NOAA can you point to another noaa-emc repo that manages the doxygen support with a gh-pages branch?

[MatthewMasarik-NOAA]

@MatthewMasarik-NOAA can you point to another noaa-emc repo that manages the doxygen support with a gh-pages branch?

@JessicaMeixner-NOAA here's a repo from NCEPLIBS (NCEPLIBS-wrf_io) that hosts doxygen output on the gh-pages branch.

[JessicaMeixner-NOAA]

Thanks @MatthewMasarik-NOAA

I see that we're following a format done by others.

A few questions:

• I see that this PR adds png files, which we try to avoid when possible. I'm assuming we've confirmed that this is a small amount of binary files and that these should not be changing and therefore adding to the size of the github repo significantly?
• I also saw that this is just a significant number of new files. I see in (NCEPLIBS-wrf_io) that these files haven't been changed in 4 years, so perhaps these are fairly static files and not a big concern.

Once you've addressed those two concerns, I see no issues with accepting this PR as is. One follow-up PR we should do is update the main readme with a link to https://NOAA-EMC.github.io/WW3

Also - we should think about creating documentation about how to keep the doxygen page upto date moving forward. (Apologies if that already exists and I just don't remember).

This will be a really nice addition to WW3!

[edwardhartnett]

We do not do pull requests to the gh-pages branch, since code review of the generated html files is meaningless. Documentation changes are reviewed with the code in PRs to the develop branch.

Only the develop branch should be protected, the gh-pages branch can be updated by @MatthewMasarik-NOAA without a PR, from the command line.

Similarly the gh-pages branch should not have any testing in the CI, it should have nothing except the built documentation.

The gh-pages branch is a bit of an odd bird. It is not code, yet it is committed to the repo. Weird. But it's a handy free way to serve the web documentation.

On the NCEPLIBS, we release versioned documentation with the releases. That is, for the g2c-2.0.0 release, there is a documentation set labeled 2.0.0. When g2c-2.1.0 is released, we release another documentation set for 2.1.0.

On gh-pages I keep subdirectories for each old released version, and the main directory holds the web files for the most recent release. Then in docs/user_guide.md I have links to old versions of the documentation. See the g2c project for an example.

[MatthewMasarik-NOAA]

Thanks @MatthewMasarik-NOAA

I see that we're following a format done by others.

I did follow the naming convention and some recommendations from @edwardhartnett. However, I think what you're seeing as the format is just the default look/style that doxygen generates. If you look at other NCEPLIB pages you see they all have that same general appearance (colors, fonts, left navigation, title frame, etc).

[edwardhartnett]

Also not that if you don't like the default format, style-sheets can be used. Google doxygen style sheets for example.

But the default looks fine and almost matches the NOAA blue, we we just use that.

[JessicaMeixner-NOAA]

Format looks great! By a format done by others, I was referring to creation of the gh-page branch. This all looks like the normal procedure - however I do think we should confirm that we wont be adding tons of new png or other binary files before merging this. I'm assuming not.

We also need to make sure we've documented how to update this and maintain it moving forward. There might be some shared documentation across EMC we can just point to as well. This can be done after the fact, just want to make sure we have this somewhere.

[MatthewMasarik-NOAA]

A few questions:

• I see that this PR adds png files, which we try to avoid when possible. I'm assuming we've confirmed that this is a small amount of binary files and that these should not be changing and therefore adding to the size of the github repo significantly?
• I also saw that this is just a significant number of new files. I see in (NCEPLIBS-wrf_io) that these files haven't been changed in 4 years, so perhaps these are fairly static files and not a big concern.

Both the files (mostly *.html) and small number of .png's are generated automatically by doxygen and are all for rendering the output webpages (note: as @edwardhartnett pointed out, the source code and the CI have been removed from this branch).

The size of the gh-pages branch should only grow slightly as new pages are added to it. I guess these added web files and pngs are the price to pay for hosting on github-pages, which is free and handy.

[MatthewMasarik-NOAA]

I do think we should confirm that we wont be adding tons of new png or other binary files before merging this.

Confirmed. The only files added are HTML, javascript, and png's needed to render the web content.

[JessicaMeixner-NOAA]

Thanks @MatthewMasarik-NOAA for leading the effort to get this done!! This is a great addition to WW3. Looking forward to following up on getting a link in the develop branch and documentation of the update/ maintenance process.

[MatthewMasarik-NOAA]

One thing I forgot to mention, you can view this documentation locally anytime you have a web browser. From the root directory, using firefox as an example browser

git checkout gh-pages
firefox index.html

would pull up the same landing page as the online version in a firefox window.