4. Documentation Maintenance Guide

PyEQSP uses Sphinx and ReadTheDocs (RTD) to deliver both the User and Maintenance guides in a unified book series format.

4.1. Technology Stack

  • Sphinx: The core documentation generator.

  • MyST-Parser: Enables writing documentation in Markdown (.md) while retaining Sphinx features (tables, cross-references).

  • Sphinx RTD Theme: Provides the responsive, premium look and feel.

4.2. Local Build Workflow

To build and preview the documentation locally:

  1. Install Dependencies:

    pip install ".[docs]"

  2. Execute Build:

    cd doc && make html

  3. Review: Open doc/_build/html/index.html in your browser.

4.3. Docstring Standards

To ensure automated API extraction works correctly, follow the Google Style Python Docstrings.

  • Always document parameters, return values, and types.

  • Include a “Notes” section for mathematical formulas (\(S^2\), \(O(N)\)).

4.4. ReadTheDocs (RTD) Strategy

The project is configured with GitHub webhooks.

  • Automation: Every push to main triggers a build of the “Latest” version.

  • Versioning: Branch tags (e.g., release_0_99_4) can be specifically enabled on the RTD dashboard to preserve documentation for older releases.

4.5. SourceForge Mirroring

While ReadTheDocs is our primary documentation host, we maintain a secondary mirror on SourceForge to ensure high-availability and persistence for research citations.

4.6. Automated Quality Safeguards

To prevent documentation drift and common technical errors, PyEQSP includes a suite of automated checks integrated into verify_all.py:

  • Link & Citation Check (validation/check_links.py): Validates all internal anchors, cross-file {ref} targets, and citation links.

  • Function Existence Check (validation/quality_check.py): Scans all guides and README.md to ensure any code snippet referencing eqsp.<func> actually exists in the current package version. This prevents “ghost” references like the legacy plot_regions_2d.

  • Coordinate Convention Check: Validates that array shape descriptions in documentation follow the column-major (dim+1, N) convention rather than the common Row-major error.

  • Matplotlib Initialization Check: Enforces that matplotlib.use('Agg') is called before any pyplot imports in examples to ensure headless environment compatibility.

  • Configuration Type Check: Validates that doc/conf.py variables use the correct data types expected by Sphinx extensions.

  • Orthography Check (validation/quality_check.py): Enforces the project’s linguistic standard (Australian -ize English), flagging non-compliant spellings (e.g., “-ise” suffixes) to ensure global academic consistency.

  • Readability Check (validation/compute_readability.py): Calculates Flesch-Kincaid and Gunning-Fog scores to monitor prose complexity and prevent academic drift.

4.7. Optional Linting: Vale

The project is configured for Vale, a prose linter that checks for style, clarity, and readability.

  • Configuration: Uses .vale.ini and a custom .vale/styles directory.

  • Rulesets: Integrates proselint, write-good, and Readability.

  • Manual Execution: To run a manual prose audit, use:

    vale README.md doc/*.md

  • Optional Status: Vale is not currently part of the mandatory verify_all.py suite. If you do not have Vale installed, the standard verification process will still pass.

To ensure stability across CI/CD and diverse local environments, these scripts are designed with architectural isolation (using independent sys.path setup) and headless environment support (automatically forcing matplotlib.use('Agg') if executed on a machine without a display).

4.8. Guide Lifecycle

  • Volume 1 (User): Should be updated whenever a new public feature or visualization method is added.

  • Volume 2 (Maintenance): Should be updated when internal architecture changes (e.g., transitioning from Mayavi to a new 3D engine) or when benchmarks are re-run.

4.8.1. Automated SourceForge Upload

The project includes a utility script to automate the Sphinx build and print the exact transfer command for the SourceForge mirror:

python release/upload_sourceforge.py

4.8.2. Manual Deployment

If you need to manually push a documentation update, follow these steps:

  1. Build HTML locally:

    cd doc && make html

  2. Transfer via SCP: (Replace USER with your SourceForge username)

    scp -r doc/_build/html/* USER@web.sourceforge.net:/home/project-web/pyeqsp/htdocs/

  3. Verify: The documentation will be instantly live at http://pyeqsp.sourceforge.io.