Skip to content

documentation_maintenance.md

Latest commit

 

History

History
91 lines (66 loc) · 4.62 KB

documentation_maintenance.md

File metadata and controls

91 lines (66 loc) · 4.62 KB
Raw

Documentation Maintenance Guide

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

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.

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.

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)$).

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.

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.

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.

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).

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 3D rendering engines) or when benchmarks are re-run.

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

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.