Write Documentation

Write Documentation#

Overview#

CrocoDash documentation is built using Sphinx and written in MyST (Markedly Structured Text) Markdown format. The documentation lives in two places:

  1. in the docs/source folder and is hosted on GitHub Pages.

  2. In a submodule and github repo called CrocoGallery, which hosts tutorials and a gallery for CrocoDash. This is also hosted on github pages, and is officially a Jupyter Book, which also runs in MyST. This is built and published similar to CrocoDash, but the frameowrk jupyter book is a bit different.

Building Documentation#

Basic Build#

  1. Activate the conda environment:

    mamba activate CrocoDash

  2. Navigate to the docs folder:

    cd docs

  3. Build HTML documentation:

    make html

    This generates HTML files in docs/build/html/. Open index.html in your browser to view the built documentation. Pushing to a PR or main will build the docs online.

Clean Build#

If documentation seems stale or you encounter build errors, perform a clean build:

cd docs
make clean
make html

This removes cached build files and rebuilds from scratch.

Regenerating API Documentation#

When you add new modules or submodules to CrocoDash, you need to regenerate the auto-documentation from docstrings:

cd docs
sphinx-apidoc -o source/api-docs ../CrocoDash # This reads the code of CrocoDash and loads it into source/apidocs
# You may consider deleting the regional_mom6 api docs, regional_mom6 has its own docs (which is what I've been doing.)
make html

Why this is needed: The API docs are auto-generated from your Python docstrings. When you add new modules, Sphinx needs to scan them and create .rst files documenting the public API.

When to do this:

  • You create a new module or submodule under CrocoDash/

  • You add new public classes or functions to existing modules

  • You significantly restructure the package

Note: The sphinx-apidoc command creates/updates files in source/api-docs/. These are referenced in the main documentation structure.

Local Server Preview#

If you’re on a supercomputer or want to preview documentation in a browser:

cd docs
make serve

This starts a local web server. The command will print a URL (typically http://127.0.0.1:8080) that you can access. Locally, just open the index.html file instead, don’t start a server.

MyST Markdown Format#

CrocoDash documentation uses MyST, which extends standard Markdown with Sphinx capabilities. It’s powerful and modern! Take full advantage, we don’t use RST for a reason.

Documentation Structure#

The documentation is organized as follows:

docs/source/
├── index.md                 # Main landing page
├── installation.md          # Installation instructions
├── for_users/               # User-focused documentation
│   └── index.md
├── for_developers/          # Developer documentation
│   ├── index.md
│   ├── docs.md              # This file
│   └── ...
├── api-docs/                # Auto-generated API documentation
│   ├── modules.rst
│   └── ...
├── raw_data_access/         # See more about this below
└── _static/                 # Static files (CSS, images, etc.)

Sphinx Configuration#

Sphinx configuration is in docs/source/conf.py. Key settings:

  • extensions - Sphinx extensions loaded (MyST, theme, etc.)

  • html_theme - The theme used

  • myst_enable_extensions - MyST-specific extensions enabled

Usually you don’t need to modify this, but consult it if you’re using advanced Sphinx features.

Raw Data Access#

Every night, there is a CI action (in raw_data_access_testing.yml) to check if the datasets are accessible. Those are then updated on a page in the documentation, https://crocodile-cesm.github.io/CrocoDash/reports/raw_data_status.html. The code to check the raw_data_access is in the raw_data_access subfolder of docs/source, called check_raw_data.py. There is also a script called generate_info.py that generates the two tables in the same folder which list the products and functions available. This is run when the docs are built.

Diagrams#

The diagrams are generated from the scripts in docs/source/diagrams. They run when the docs are built.

Common Errors#

The Common Errors link on the docs is just a Github Dicussion on CrocoDash! Feel free to add anything to that.

Publishing Documentation (This is important! Read This!)#

CrocoDash documentation is automatically published to GitHub Pages when you push to the main branch (via GitHub Actions or similar CI/CD). No manual steps are required, but ensure:

  1. Your documentation builds locally without errors

  2. All cross-references are valid

  3. You’ve committed and pushed changes to GitHub

How it is built is with a github action called deploy_sphinx_docs.yml. What it does is build the docs, and based on if its a PR or a push to main, pushes the files to a folder in the gh-pages branch in the repo. Github Settings Pages is setup to deploy everytime there is a push to gh_pages. This deploys everything in gh-pages. This means a subfolder called workshop, will show up under the link crocodile-cesm.github.io/CrocoDash/workshop, and one called “pr-28” will show up under the sublink /pr-28/. This is useful because of how we setup the docs.

Old versions of the docs may be set under links workshop (which I’ve set up manually), the latest push to main is under the subfolder /latest/. Prs are in /pr-xx/. The main index page just reroutes to /latest/

Troubleshooting#

API docs not appearing#

Check that:

  1. You ran sphinx-apidoc -o source/api-docs ../CrocoDash

  2. The generated files exist in source/api-docs/

  3. The api-docs/modules is referenced in index.md toctree

Documentation not updating after changes#

Try a clean build:

make clean
make html

The HTML files are cached; cleaning removes stale caches.

Broken cross-references#

Ensure that:

  1. The file path is correct (relative to the docs source)

  2. You use the correct Sphinx role syntax: {py:class}, {py:func}, etc.

  3. The Python object actually exists and is properly imported

Best Practices#

  1. Use Clear Headings - Organize content with proper heading hierarchy (# for main, ## for sections, etc.)

  2. Write Docstrings - Add docstrings to all public functions, classes, and modules; API docs pull from these

  3. Link to Code - Use cross-references to link documentation to actual code

  4. Test Links - After building, check that internal and external links work

  5. Keep It Updated - Update documentation when you change the API or add features

  6. Use Admonitions - Highlight warnings, notes, and important information

  7. Provide Examples - Include code examples where helpful

  8. Review Locally - Always build and review documentation locally before pushing

Contents