Building Documentation

Purpose and Scope

This document explains how to build the pyjiit documentation locally using Sphinx. It covers the Sphinx configuration in docs/conf.py, the Furo theme setup, required dependencies, and the build process. For information about automated deployment to GitHub Pages, see Documentation Deployment. For guidelines on writing documentation content and using reStructuredText, see Contributing to Documentation.

Sources: docs/conf.py1-49

Sphinx Configuration

The pyjiit documentation uses Sphinx as the documentation generator, configured via docs/conf.py. The configuration defines project metadata, enabled extensions, and theme settings.

Project Metadata

The following project information is defined at the top of the configuration:

The Python path is modified to include the parent directory (..) so that Sphinx can import the pyjiit package for autodoc extraction:

sys.path.insert(0, os.path.abspath('..'))

Sources: docs/conf.py8-15

Enabled Extensions

Two Sphinx extensions are enabled:

The autodoc extension allows Sphinx to read Python source files in pyjiit/*.py and generate API reference documentation automatically from class and function docstrings.

Sources: docs/conf.py20-23

Furo Theme Configuration

The documentation uses the Furo theme, a modern, clean Sphinx theme:

html_theme = 'furo'

Theme customization includes a footer icon linking to the GitHub repository. The icon is defined as inline SVG in the html_theme_options dictionary with three properties:

• name: Display name ("GitHub")
• url: Link destination (https://github.com/codelif/pyjiit)
• html: Inline SVG markup for the GitHub logo

Sources: docs/conf.py33-48

Documentation Build Process

Sources: .github/workflows/documentation.yml42-53 docs/conf.py1-49

Local Build Steps

To build the documentation locally, execute the following commands from the repository root:

1. Install dependencies with docs group:

   poetry install --with docs

   This installs Sphinx, Furo theme, and all pyjiit dependencies.

2. Run the Sphinx build command:

   poetry run sphinx-build -b html docs docs/_build/html

   Command arguments:

   • -b html: Build HTML output format
   • docs: Source directory containing conf.py and .rst files
   • docs/_build/html: Output directory for generated HTML files

3. View the built documentation: Open docs/_build/html/index.html in a web browser.

Sources: .github/workflows/documentation.yml45-53

Build Dependencies

Documentation dependencies are managed via Poetry's docs dependency group in pyproject.toml. The primary dependency is:

Sphinx itself is included as a dependency of the docs group. The pyjiit package is installed in editable mode, allowing autodoc to import modules from the local source tree.

Sources: docs/requirements.txt1-2

Documentation File Structure

Sources: docs/conf.py25-26 docs/conf.py34

Source Directory Layout

The docs/ directory contains:

Excluded Patterns

The configuration excludes certain patterns from processing:

exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']

This prevents Sphinx from trying to process build artifacts or OS-specific files.

Sources: docs/conf.py25-26

Integration with CI/CD

The documentation build process is automated via GitHub Actions. The workflow executes the same build steps locally available:

Sources: .github/workflows/documentation.yml1-64

Workflow Triggers

The documentation workflow (documentation.yml) runs on:

Sources: .github/workflows/documentation.yml3-8

Caching Strategy

The workflow uses two caching layers to speed up builds:

1. pip cache (via actions/setup-python@v5):

   • Caches pip's download cache
   • Keyed by cache: 'pip' parameter

2. Poetry cache (via actions/cache@v3):

   • Caches ~/.cache/pypoetry and ~/.cache/pip
   • Keyed by hash of poetry.lock and pyproject.toml
   • Restore keys: ${{ runner.os }}-poetry-

This ensures dependencies are only re-downloaded when poetry.lock or pyproject.toml changes.

Sources: .github/workflows/documentation.yml26-40

Build Command in CI

The exact command executed in CI is:

poetry run sphinx-build -b html docs docs/_build/html

After building, a CNAME file is created in the output directory for custom domain support:

echo "pyjiit.codelif.in" > docs/_build/html/CNAME

Sources: .github/workflows/documentation.yml51-54

Autodoc Integration

The sphinx.ext.autodoc extension automatically generates API documentation from Python docstrings. This integration requires:

1. Python path configuration in conf.py:

   sys.path.insert(0, os.path.abspath('..'))

   This allows Sphinx to import pyjiit modules.

2. Module imports during build: Sphinx imports classes and functions from pyjiit/wrapper.py, pyjiit/encryption.py, etc., to extract docstrings.

3. reStructuredText directives in .rst files:

   .. autoclass:: pyjiit.Webportal :members: :undoc-members:

The autodoc system reads the actual Python source code, ensuring documentation stays synchronized with implementation.

Sources: docs/conf.py8-23

Build Output Structure

Sources: .github/workflows/documentation.yml51-54 docs/conf.py22

Key Output Files

The .nojekyll file is automatically created by the sphinx.ext.githubpages extension.

Sources: docs/conf.py22 .github/workflows/documentation.yml54