Documentation Development

Documentation Development#

This guide explains the architecture and maintenance of the snowex_db documentation system.

Overview#

The snowex_db documentation uses Jupyter Book, a modern documentation framework built on Sphinx. This matches the architecture used in the companion snowexsql project, providing consistency across the SnowEx ecosystem.

Key Features#

Modern Theme#

  • Sphinx Book Theme - Professional, responsive design

  • Dark mode support

  • Mobile-friendly layout

  • Consistent with snowexsql documentation

Cross-Project Linking#

Intersphinx is configured to link to snowexsql documentation, allowing you to reference snowexsql classes and functions directly.

Example: :py:class:`snowexsql.LayerData`

Development Tools#

  • make live - Live-reload server for instant preview

  • make docs - Build and automatically open in browser

  • sphinx-autobuild - Automatic rebuilding on file changes

Modern Extensions#

  • sphinx_copybutton - One-click code copying

  • sphinx_design - Modern UI components

  • myst_nb - Enhanced notebook integration

  • sphinx_togglebutton - Collapsible content sections

Local Development#

Installing Dependencies#

Install the package with documentation dependencies:

pip install -e ".[docs]"

Building Documentation#

Basic build:

cd docs
make html

Build and open in browser:

cd docs
make docs

Live development with auto-rebuild:

cd docs
make live

This starts a local server that automatically rebuilds the documentation when you save changes.

Configuration Architecture#

Jupyter Book 1.x uses a two-file configuration system:

Source of Truth: _config.yml#

The docs/_config.yml file is the source of truth for all configuration. Edit this file to:

  • Control book-level options

  • Configure Sphinx settings under the sphinx: section

  • Add or remove extensions under sphinx.extra_extensions

  • Set Sphinx options under sphinx.config

Generated File: conf.py#

The docs/conf.py file is auto-generated from _config.yml. Do not edit this file manually, as it will be overwritten.

Configuration Workflow#

  1. Make all configuration changes in docs/_config.yml

  2. Regenerate the Sphinx configuration:

    cd docs
jupyter-book config sphinx .

    Note: This happens automatically on ReadTheDocs in the pre_build job.

  3. Clean build to test changes:

    cd docs
make clean && make html

Example Configuration Changes#

To add a new Sphinx extension, edit _config.yml:

sphinx:
  extra_extensions:
    - sphinx.ext.napoleon
    - sphinx.ext.todo

To modify Sphinx settings, edit _config.yml:

sphinx:
  config:
    html_theme_options:
      logo: "logo.png"
    autodoc_default_options:
      members: true
      undoc-members: true

API Documentation#

The project uses two complementary extensions for API documentation:

sphinxcontrib-apidoc#

Automatically scans your Python package and generates .rst stub files with automodule directives for each module.

Configuration in _config.yml:

sphinx:
  config:
    apidoc_module_dir: '../snowex_db'    # Package to scan
    apidoc_output_dir: './api'           # Where to write files
    apidoc_separate_modules: true        # One page per module

Note

The generated API .rst files in docs/api/ are auto-generated and should not be committed to version control. They are listed in .gitignore.

sphinx.ext.autodoc#

Renders Python docstrings from your code into the documentation pages during the build.

Quality Improvements#

Consider adding these settings to _config.yml for better API documentation:

sphinx:
  extra_extensions:
    - sphinx.ext.napoleon  # Support Google/NumPy-style docstrings
  config:
    autodoc_default_options:
      members: true
      undoc-members: true
      inherited-members: true
      show-inheritance: true
    autodoc_typehints: description

Adding API Pages to Navigation#

Generated API pages are automatically included via the api/modules entry in _toc.yml.

ReadTheDocs Integration#

The .readthedocs.yaml file configures the ReadTheDocs build:

build:
  os: ubuntu-22.04
  tools:
    python: "3.11"
  jobs:
    pre_build:
      - "jupyter-book config sphinx docs"

python:
  install:
    - method: pip
      path: .
      extra_requirements:
        - docs

Writing Documentation#

File Formats#

Jupyter Book supports both:

  • reStructuredText (.rst) - Traditional Sphinx format

  • Markdown (.md) - With MyST-Parser extensions

All existing .rst files continue to work without modification.

Adding New Pages#

  1. Create your documentation file in docs/

  2. Add it to docs/_toc.yml:

    chapters:
  - file: your_new_page
  - file: another_page

  3. Build to verify:

    make html

Cross-References#

Reference other snowex_db pages:

See :doc:`installation` for setup instructions.

Reference snowexsql documentation (via Intersphinx):

Use :py:class:`snowexsql.LayerData` to query layer data.

Adding Jupyter Notebooks#

Jupyter notebooks can be added directly to the documentation and will be rendered automatically.

Creating a Notebook Example#

  1. Create a new Jupyter notebook in docs/gallery/ (or another appropriate location)

  2. Name it with a descriptive title: your_example.ipynb

  3. Structure your notebook:

    • Start with a markdown cell explaining the goal

    • Use ### headers for steps (shows up in table of contents)

    • Include code cells with examples

  4. Add thumbnail tags to a cell with figures:

    • Click on the cell

    • Open the property inspector (double gear icon)

    • Add tags: nbsphinx-thumbnail and nbsphinx-gallery

  5. Add the notebook to _toc.yml:

    chapters:
  - file: gallery/your_example

Notebook Execution#

By default, notebooks are not executed during the build (nb_execution_mode: 'off' in conf.py).

To enable automatic execution, modify _config.yml:

sphinx:
  config:
    nb_execution_mode: 'auto'
    nb_execution_timeout: 60

Troubleshooting#

Build Fails: “jupyter-book not found”#

Install documentation dependencies:

pip install -e ".[docs]"

ReadTheDocs Build Fails#

Verify:

  • pyproject.toml has [project.optional-dependencies] with docs section

  • .readthedocs.yaml references extra_requirements: docs

  • _config.yml is valid YAML

Cross-References Don’t Work#

For snowexsql cross-references:

  • Ensure snowexsql documentation is published and accessible

  • Check intersphinx_mapping in _config.yml

  • Verify the inventory file is accessible (may need to build snowexsql docs first)

API Documentation Not Generating#

Check:

  • sphinxcontrib-apidoc is in the extensions list

  • apidoc_module_dir points to the correct Python package

  • Your Python package is importable (dependencies installed)

Optional Enhancements#

Add Citations/References#

For academic use:

  1. Create docs/references.bib with BibTeX entries

  2. Configure in _config.yml:

    bibtex_bibfiles:
  - references.bib

  3. Use citations in documentation: :cite:`key`

Dark Mode Customization#

Customize theme colors in _config.yml:

sphinx:
  config:
    html_theme_options:
      pygment_light_style: tango
      pygment_dark_style: monokai

References#

Contents