Enable doxygen in cmake build

[MatthewMasarik-NOAA]

Pull Request Summary

Enables doxygen documention within the cmake build system.

Description

Doxygen support is added to the build system via:

• A cache variable (ENABLE_DOCS) is added to the main CMakeLists.txt file, which is currently set to OFF by default.
• A cmake module is added (EnableDoxygen) which takes an output directory as an argument. Default is set as docs.
• EnableDoxygen adds a target (enable_docs) to the build system. If doxygen is not found on the system, the target will fail, otherwise doxygen will be run and the output location of index.html is displayed during cmake config.
• There are only changes to the cmake build files to handle doxygen documentation, so there are no answer changes expected.

Usage

Steps to generate doxygen documentation from the WW3 root directory:

mkdir build && cd build
cmake -DSWITCH=<path-to-switch> -DENABLE_DOCS=ON -S .. -B .
cmake --build . --target enable_docs                         # make enable_docs

View html docs in browser (ex, firefox) for default output location

firefox docs/html/index.html

• Tested using doxygen v1.8.17.
• Note that it's not necessary to build the model to generate the doxygen documentation. Specifying the target enable_docs will just run doxygen on the source files. However, the dependencies (i.e, Fortran compiler, NetCDF, etc) still need to be available due to checks within the build system.

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.

Issue(s) addressed

• fixes Add doxygen to the build #1171
• A follow-on PR will address Add io page for manual #25

Commit Message

Enable doxygen documentation in the cmake build system

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 documentation and verifying output in a browser (ubuntu 20.04, doxygen 1.8.17, mozilla firefox 128.0). The current default doxygen documentation homepage:

• Are the changes covered by regression tests? (If not, why? Do new tests need to be added?)
  • No. Documentation is not tested.
• 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.

[MatthewMasarik-NOAA]

Thanks for your review @edwardhartnett

[AlexanderRichert-NOAA]

You could consider using the 'required' keyword for find_package(Doxygen), or use a fatal error if not found, that way if it's not found it should get caught sooner and more conspicuously. But I've tested building the docs (and tested Doxygen not found) and it looks good.

[MatthewMasarik-NOAA]

You could consider using the 'required' keyword for find_package(Doxygen), or use a fatal error if not found, that way if it's not found it should get caught sooner and more conspicuously. But I've tested building the docs (and tested Doxygen not found) and it looks good.

Thanks @AlexanderRichert-NOAA, that's a great suggestion. I'll update 'find_package' to use the 'required' keyword.

[JessicaMeixner-NOAA]

Approving based on @edwardhartnett and @AlexanderRichert-NOAA review

[MatthewMasarik-NOAA]

Approving based on @edwardhartnett and @AlexanderRichert-NOAA review

Thank you for reviewing @JessicaMeixner-NOAA