diff --git a/.readthedocs.yaml b/.readthedocs.yaml index c74a9b5e..df08a35c 100644 --- a/.readthedocs.yaml +++ b/.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 diff --git a/docs/Doxyfile b/docs/Doxyfile new file mode 100644 index 00000000..22ea0acc --- /dev/null +++ b/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 diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..d6555c00 --- /dev/null +++ b/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 +``` diff --git a/docs/conf.py b/docs/conf.py index c0b6684b..3ed4da4d 100644 --- a/docs/conf.py +++ b/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 diff --git a/docs/develop/developers_guide.rst b/docs/develop/developers-guide.rst similarity index 65% rename from docs/develop/developers_guide.rst rename to docs/develop/developers-guide.rst index 14c71270..d60145f1 100644 --- a/docs/develop/developers_guide.rst +++ b/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/ + +- Each process should include a process driver named ``CCPr__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. diff --git a/docs/develop/development_team.rst b/docs/develop/development-team.rst old mode 100755 new mode 100644 similarity index 93% rename from docs/develop/development_team.rst rename to docs/develop/development-team.rst index f509be24..f7eadfd8 --- a/docs/develop/development_team.rst +++ b/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``) diff --git a/docs/doxygen/.gitignore b/docs/doxygen/.gitignore new file mode 100644 index 00000000..424ba36a --- /dev/null +++ b/docs/doxygen/.gitignore @@ -0,0 +1,3 @@ +* +!.gitignore +!index.md diff --git a/docs/doxygen/index.md b/docs/doxygen/index.md new file mode 100644 index 00000000..bdfa9ecc --- /dev/null +++ b/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. diff --git a/docs/environment-docs.yml b/docs/environment-docs.yml index 92f5c556..de06674c 100644 --- a/docs/environment-docs.yml +++ b/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 diff --git a/docs/index.rst b/docs/index.rst index ace1ffca..7b794f31 100644 --- a/docs/index.rst +++ b/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 diff --git a/docs/tweaks.css b/docs/tweaks.css new file mode 100644 index 00000000..e0b7a9fd --- /dev/null +++ b/docs/tweaks.css @@ -0,0 +1 @@ +#projectname {display:none} diff --git a/docs2/Doxyfile b/docs2/Doxyfile index e14c95e8..e612fd60 100644 --- a/docs2/Doxyfile +++ b/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 diff --git a/docs2/start.md b/docs2/start.md index c6d4b7d8..f7085d18 100644 --- a/docs2/start.md +++ b/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.