RFC: add auto generated c++ api docs via mkdoxy

[mahf708]

example mkdocs.yaml mods to get it working reasonably well (testing for the emulators comps, because I am trying to establish good protocols for that at the outset in terms of docs)

diff --git a/mkdocs.yaml b/mkdocs.yaml
index e2a806af55..622db78158 100644
--- a/mkdocs.yaml
+++ b/mkdocs.yaml
@@ -41,6 +41,8 @@ theme:
     - navigation.sections
     - navigation.path
     - navigation.tracking
+    - navigation.path
+    - navigation.tracking
     - navigation.top
     - search.suggest
     - search.highlight
@@ -56,7 +58,11 @@ markdown_extensions:
   - footnotes
   - pymdownx.details
   - pymdownx.highlight
-  - pymdownx.superfences
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
   - pymdownx.tabbed:
       alternate_style: true
   - pymdownx.arithmatex:
@@ -73,6 +79,18 @@ plugins:
   - search
   - bibtex:
       bib_dir: docs/refs
+  - mkdoxy:
+      projects:
+        emulator_api:
+          src-dirs: components/emulator_comps/common/src components/emulator_comps/eatm/src
+          full-doc: True
+          api-path: Emulators/emulator_api
+          save-api: True
+          doxy-cfg:
+            FILE_PATTERNS: "*.cpp *.hpp"
+            RECURSIVE: True
+            EXTRACT_ALL: True
+            JAVADOC_AUTOBRIEF: True
 extra:
   analytics:
     provider: google

The key section is obviously the - mkdoxy one, and we can do stuff like:

+  - mkdoxy:
+      projects:
+        emulators:
+          src-dirs: components/emulator_comps/common/src components/emulator_comps/eatm/src
+          api-path: Emulators/api
+        eamxx:
+          src-dirs: components/eamxx/... ...
+          api-path: EAMxx/api
+        omega:
+          src-dirs: components/omega/... ...
+          api-path: Omega/api

pls discuss and weigh in; cc @rljacob + @bartgol, and pls feel free to tag others (RFC = request for comment)

• update: added mkdoxy to conda-forge

[mahf708]

example in #7964

[bartgol]

I'm not following. What issue is the mkdoxy section addressing?

[mahf708]

It produces stuff like https://docs.e3sm.org/E3SM/pr-preview/pr-7964/Emulators/emulator/links/ and https://docs.e3sm.org/E3SM/pr-preview/pr-7964/Emulators/emulator/classemulator_1_1EmulatorComp/

[bartgol]

Uhm, I am not sure I like it. It looks a lot like Doxygen, which I never really liked. Most of the generated stuff does not add much, as it simply lists the name of the class, class member, type, etc. In order to make it useful, we need to add quite a bit of comments to the source code, which makes the everyday life of developers a bit harder (the length of the hpp files grows quickly).

[mahf708]

Yeah, that's the goal of the RFC. The benefit could be enabling a rendered version of the docs so that it could be viewed in the docs, etc., with search functionality and all. I think there's an argument it gives some users the ability to digest the code without opening the corresponding files in an editor or gh, etc.

[mahf708]

I agree with the argument against verbosity and doxygen (mkdoxy is simple a wrapper over doxygen btw)