===========================
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:

.. code-block:: bash

   pip install -e ".[docs]"

Building Documentation
~~~~~~~~~~~~~~~~~~~~~~

Basic build:

.. code-block:: bash

   cd docs
   make html

Build and open in browser:

.. code-block:: bash

   cd docs
   make docs

Live development with auto-rebuild:

.. code-block:: bash

   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:

   .. code-block:: bash

      cd docs
      jupyter-book config sphinx .

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

3. Clean build to test changes:

   .. code-block:: bash

      cd docs
      make clean && make html

Example Configuration Changes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

.. code-block:: yaml

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

To modify Sphinx settings, edit ``_config.yml``:

.. code-block:: yaml

   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``:

.. code-block:: yaml

   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:

.. code-block:: yaml

   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:

.. code-block:: yaml

   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``:

   .. code-block:: yaml

      chapters:
        - file: your_new_page
        - file: another_page

3. Build to verify:

   .. code-block:: bash

      make html

Cross-References
~~~~~~~~~~~~~~~~

Reference other snowex_db pages:

.. code-block:: rst

   See :doc:`installation` for setup instructions.

Reference snowexsql documentation (via Intersphinx):

.. code-block:: rst

   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``:

   .. code-block:: yaml

      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``:

.. code-block:: yaml

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

Troubleshooting
---------------

Build Fails: "jupyter-book not found"
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Install documentation dependencies:

.. code-block:: bash

   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 a Logo
~~~~~~~~~~

Edit ``docs/_config.yml``:

.. code-block:: yaml

   logo: logo.png  # Place logo.png in docs/ directory

Create an Example Gallery
~~~~~~~~~~~~~~~~~~~~~~~~~~

Like snowexsql, you can create a gallery of examples:

1. Create ``docs/gallery/`` directory
2. Add example notebooks or ``.py`` files
3. Update ``_toc.yml`` to include the gallery section

Add Citations/References
~~~~~~~~~~~~~~~~~~~~~~~~~

For academic use:

1. Create ``docs/references.bib`` with BibTeX entries
2. Configure in ``_config.yml``:

   .. code-block:: yaml

      bibtex_bibfiles:
        - references.bib

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

Dark Mode Customization
~~~~~~~~~~~~~~~~~~~~~~~

Customize theme colors in ``_config.yml``:

.. code-block:: yaml

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

References
----------

- `Jupyter Book Documentation <https://jupyterbook.org/>`_
- `Sphinx Book Theme <https://sphinx-book-theme.readthedocs.io/>`_
- `MyST-Parser (Markdown) <https://myst-parser.readthedocs.io/>`_
- `snowexsql Documentation <https://snowexsql.readthedocs.io/>`_
- `Sphinx Documentation <https://www.sphinx-doc.org/>`_