Merge pull request #110 from zmoon/doxy

Doxysphinx

.readthedocs.yaml

@@ -1,9 +1,13 @@
 version: 2
 
 build:
-  os: "ubuntu-20.04"
+  os: "ubuntu-22.04"
   tools:
-    python: "mambaforge-4.10"
+    python: "mambaforge-22.9"
+  jobs:
+    pre_build:
+      - cd docs && doxygen Doxyfile
+      - cd docs && doxysphinx build . $READTHEDOCS_OUTPUT/html/ Doxyfile
 
 sphinx:
   configuration: docs/conf.py

docs/Doxyfile

@@ -0,0 +1,44 @@
+# https://www.doxygen.nl/manual/config.html
+PROJECT_NAME = CATChem
+PROJECT_BRIEF =
+
+OPTIMIZE_FOR_FORTRAN = YES
+
+INPUT = doxygen/index.md \
+        ../src/core \
+        ../src/process/drydep \
+        ../src/process/dust \
+        ../src/process/plumerise \
+        ../src/process/seasalt \
+        ../src/api
+USE_MDFILE_AS_MAINPAGE = index.md
+FILE_PATTERNS = *.F90
+RECURSIVE = YES
+
+# Doxygen Awesome
+HTML_EXTRA_STYLESHEET = ../docs2/static/doxygen-awesome.css \
+                        ../docs2/static/doxygen-awesome-sidebar-only.css \
+                        tweaks.css
+HTML_COLORSTYLE = LIGHT
+
+# Doxysphinx required
+GENERATE_TREEVIEW = NO
+DISABLE_INDEX = NO
+GENERATE_HTML = YES
+CREATE_SUBDIRS = NO
+OUTPUT_DIRECTORY = ./doxygen/
+GENERATE_LATEX = NO
+
+# Doxysphinx recommended
+SEARCHENGINE = NO
+GENERATE_TAGFILE = ./doxygen/html/tagfile.xml
+DOT_IMAGE_FORMAT = svg
+DOT_TRANSPARENT = YES
+INTERACTIVE_SVG = YES
+ALIASES = "rst=\verbatim embed:rst:leading-asterisk" \
+          endrst=\endverbatim
+
+# GraphViz Configuration
+INCLUDE_GRAPH = NO
+INCLUDED_BY_GRAPH = NO
+CALL_GRAPH = YES

docs/README.md

@@ -0,0 +1,24 @@
+Building the docs locally:
+
+(From this directory.)
+
+1. Run Doxygen
+   ```
+   doxygen
+   ```
+
+2. Run Doxysphinx
+   ```
+   doxysphinx -v INFO build . ./_build Doxyfile
+   ```
+
+3. Run Sphinx
+   ```
+   sphinx-build -b html . ./_build
+   ```
+
+Or, in one line:
+
+```bash
+doxygen && doxysphinx -v INFO build . ./_build Doxyfile && sphinx-build -b html . ./_build
+```

docs/conf.py

@@ -85,7 +85,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -103,6 +103,7 @@
 # a list of builtin themes.
 #
 html_theme = 'sphinx_rtd_theme'
+# html_theme = 'sphinx_book_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the

docs/develop/developers_guide.rst → docs/develop/developers-guide.rst

@@ -1,7 +1,7 @@
 Developer's Guide
 =================
 
-Description of Branches
+Description of branches
 -----------------------
 
 main
@@ -18,7 +18,7 @@ when cloning the repository.
 .. _dev-install-instructions:
 
 How to incorporate updates to CATChem
---------------------------------------------
+-------------------------------------
 
 In order to contribute code to CATChem, you will need to fork the
 repository, make changes on your fork, and submit a pull request with your
@@ -74,3 +74,29 @@ changes.
    you can still clone the repositories via HTTPS, e.g. ::
 
        $ git clone https://github.com/ufs-community/CATChem.git
+
+How to add a new *process*
+--------------------------
+
+CATChem is developed to be able to be easily extensible with new processes.
+There are just a few steps that are required to be able to include a new process.
+
+- First create a new directory under src/process for your new process::
+
+    $ cd src/process
+    $ mkdir src/process/<new process>
+
+- Each process should include a process driver named ``CCPr_<new process>_Mod.F90``.
+  You can find a template under ``src/process/Process_driver_template.F90``.
+  In it, each process driver contains three phases:
+
+  * Init: Processes the config and initializes process defaults if activated
+  * Run: Runs the process and adds to ``DiagState`` and ``ChemState`` for any process
+  * Finalize: Deallocate any arrays that were allocated.
+
+- Each process should include a common module for any functions that may be used by schemes
+  (sub-parameterizations or common calculations between different schemes in that process family).
+  It also houses the process type and data information.
+
+- Each process then can have one or more schemes within them.
+  An example can be seen under ``src/process/dust`` and a template.

docs/develop/development_team.rst → docs/develop/development-team.rst

@@ -5,7 +5,7 @@ Code Reviewers
 --------------
 
 ================= ========================================================
-Organization      Reviewers (github username)
+Organization      Reviewers (GitHub username)
 ================= ========================================================
 NOAA CSL          Colin Harkins (``colin-harkins``), Jian He (``jianheACM``), Quazi Rasool (``quaz115``), Becky Schwantes (``rschwant``)
 NOAA ARL          Zach Moon (``zmoon``), Barry Baker (``bbakernoaa``), Patrick Campbell (``drnimbusrain``)

docs/doxygen/.gitignore

@@ -0,0 +1,3 @@
+*
+!.gitignore
+!index.md

docs/doxygen/index.md

@@ -0,0 +1,3 @@
+CATChem API documentation generated by [Doxygen](https://www.doxygen.nl/) from source code comments,
+embedded in Sphinx with the help of [Doxysphinx](https://boschglobal.github.io/doxysphinx/).
+Use the sidebar and page links to navigate.

docs/environment-docs.yml

@@ -4,11 +4,18 @@ channels:
   - conda-forge
   - nodefaults
 dependencies:
-  - python=3.10
+  - python=3.11
+  - pip
   #
   # Docs
-  - sphinx=6.*
+  - doxygen=1.9.8
+  - graphviz
+  - sphinx=8.*
   - sphinx-autobuild
   - sphinx-design
+  - sphinx-book-theme
   - sphinx_rtd_theme
   - sphinx-togglebutton
+  #
+  - pip:
+    - doxysphinx

docs/index.rst

@@ -1,5 +1,5 @@
 CATChem
-==============
+=======
 
 **CATChem**  (Configurable ATmospheric Chemistry) is a modelling
 component that includes all chemical and aerosol processes needed to perform
@@ -8,18 +8,23 @@ flexible, easy to modify, and well-documented infrastructure. CATChem will
 include the following processes: chemical kinetics, aerosols, photolysis,
 wet deposition, dry deposition, connections to emissions, and connection to
 physics schemes. The first use of CATChem will be connecting it to NOAA's
-Unified Forecasting System (https://ufscommunity.org/) to create UFS-Chem. CATChem and UFS-Chem are
-currently under development and more information will be provided soon.
+Unified Forecasting System (https://ufscommunity.org/) to create UFS-Chem.
+CATChem and UFS-Chem are currently under development and more information will be provided soon.
 
 
 .. warning::
-   CATChem is currently under development. The code is public to
-   encourage collaboration amongst the community. Do not publish results using
-   CATChem  without consulting the development team.
+   CATChem is currently under development.
+   The code is public to encourage collaboration amongst the community.
+   Do not publish results using CATChem without consulting the development team.
 
 .. toctree::
    :maxdepth: 1
    :caption: Contribute
 
-   develop/development_team
-   develop/developers_guide
+   develop/development-team
+   develop/developers-guide
+
+.. toctree::
+   :caption: Reference
+
+   API <doxygen/html/index>

docs/tweaks.css

@@ -0,0 +1 @@
+#projectname {display:none}

docs2/Doxyfile

@@ -15,7 +15,9 @@ BRIEF_MEMBER_DESC = YES
 
 INPUT = start.md
 INPUT += ../src/core
+INPUT += ../src/process/drydep
 INPUT += ../src/process/dust
+INPUT += ../src/process/plumerise
 INPUT += ../src/process/seasalt
 INPUT += ../src/api
 USE_MDFILE_AS_MAINPAGE = start.md

docs2/start.md

@@ -2,7 +2,7 @@
 
 ## Description
 
-The Configurable ATmospheric Chemisty (CATChem) component
+The Configurable ATmospheric Chemisty (CATChem) is a modelling component
 that includes all chemical and aerosol processes needed to perform
 atmospheric chemistry and composition simulations within a model
 through a flexible, easy to modify, and well-documented infrastructure.