Sphinx Guide

This document provides instructions for contributors on how to set up, customize, and run Sphinx to generate documentation for the Biofilter project. The project uses Sphinx to maintain two separate documentations: one for user documentation and another for developer documentation.

Documentation Structure

The Biofilter project maintains two distinct documentation directories:

  1. User Documentation:

    • Located in the docs/ directory.

    • Hosted on ReadTheDocs.

    • Contains user-facing guides, usage instructions, and detailed module documentation.

  2. Developer Documentation:

    • Located in the docs-dev/ directory.

    • Hosted on GitHub Pages.

    • Contains internal technical documentation for contributors, including guides on tools like Tox, Poetry, Black, and branching strategies.

Each directory has its own Sphinx configuration file (conf.py) and operates independently.

Prerequisites

Ensure you have the following tools installed:

  • Python (>= 3.10)

  • Poetry (manages dependencies, including Sphinx)

Note

Sphinx is already included as a development dependency in the pyproject.toml file. You do not need to install it manually.

Working with Documentation

User Documentation (docs/)

To build and preview the user documentation:

  1. Navigate to the docs/ directory:

    cd docs

  2. Build the HTML documentation:

    make html

  3. Open the generated documentation in a browser:

    open _build/html/index.html

This documentation is automatically built and hosted on ReadTheDocs.

Developer Documentation (docs-dev/)

To build and preview the developer documentation:

  1. Navigate to the docs-dev/ directory:

    cd docs-dev

  2. Build the HTML documentation:

    make html

  3. Open the generated documentation in a browser:

    open _build/html/index.html

This documentation is hosted on GitHub Pages, and any updates are automatically deployed through a GitHub Actions workflow.

Important

The gh-pages branch is used exclusively for hosting the developer documentation. It is automatically managed by GitHub Actions and should not be modified manually.

Customizing Documentation

Configuration Files

Each documentation directory has its own conf.py file for configuration. Key sections to customize include:

  1. Project Information:

    project = 'Biofilter'
author = 'Ritchie Lab'
release = '2.4.4'

  2. Path Settings:

    Ensure modules are accessible to Sphinx:

    import os
import sys
sys.path.insert(0, os.path.abspath(".."))

  3. Extensions:

    Add or modify Sphinx extensions as needed:

    extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.viewcode',
    'sphinx.ext.napoleon',
    'sphinx_rtd_theme',
]

  4. HTML Theme:

    Set the theme for the documentation:

    html_theme = 'sphinx_rtd_theme'  # For user documentation
html_theme = 'sphinx_material'  # For developer documentation

Customizing and Regenerating

  1. Edit Index Files:

    • docs/index.rst: Entry point for user documentation.

    • docs-dev/index.rst: Entry point for developer documentation.

    Add or modify sections and include additional .rst files using:

    .. toctree::
    :maxdepth: 2
    :caption: Contents:

    usage-guide
    developer-guide

  2. Generate Module Documentation:

    Use sphinx-apidoc to create .rst files for modules:

    sphinx-apidoc -o . ../biofilter_modules

  3. Rebuild Documentation:

    After making changes, rebuild the documentation:

    make clean
make html

Tips for Contributors

  1. Docstrings:

    Write detailed docstrings in your codebase. Use Google or NumPy style for compatibility with the napoleon extension.

  2. Test Locally:

    Always test your changes locally by building the documentation before pushing updates.

  3. Branch Management:

    • User documentation updates should be committed to the main branch.

    • Developer documentation updates should be committed to the development branch. GitHub Actions will handle the deployment to gh-pages.

Troubleshooting

  • Sphinx Command Not Found:

    Ensure you are in the Poetry environment:

    poetry shell

  • Broken Links:

    Check for broken links using:

    make linkcheck

  • Missing Modules:

    Verify module paths in conf.py under sys.path.

Additional Resources