Maintaining the documentation

This guide is for contributors who change user guides, API pages, examples, or the publication pipeline. GitLab Pages publishes docs/next/source. The previous docs/source tree is retained temporarily as a migration fallback but is no longer maintained as the publication source.

Source layout

docs/next/source/de and docs/next/source/en

Bilingual user guides. Both trees must contain the same relative .rst paths and equivalent technical information.

docs/next/source/api

English-only API and command reference. Curated pages present the recommended public extension surface; api/full is generated.

docs/next/source/_static

Version-controlled figures and other static assets.

docs/next/MIGRATION.md

Review status for content from the published documentation and the cutover checklist.

test/test_docs_next_structure.py

Structural safeguards for language parity and important technical content.

Local setup and build

Install the project and documentation dependencies from the repository root:

python -m pip install -e ".[docs]"

Graphviz dot is a system executable, not a Python package. It is required for Graphviz directives. Build the complete documentation with warnings treated as errors:

MPLCONFIGDIR=/tmp/mpylab-matplotlib \
sphinx-build -W --keep-going -E -a -b html \
    docs/next/source build/docs

-E -a deliberately rebuilds the environment and all pages, preventing a cached build from hiding broken references. Open build/docs/index.html to inspect the result.

Run the documentation structure tests and whitespace check as well:

python -m pytest test/test_docs_next_structure.py
python tools/check_public_docstrings.py
git diff --check

Bilingual pages

Every user-facing page below one language root has a counterpart at the same relative path below the other root. Add both files and both toctree entries in one change. Keep code names, configuration keys, units, and command examples identical; translate explanation and UI terminology.

Python docstrings and API pages remain English-only. New and revised public docstrings use NumPy style. Do not create duplicate German API wrappers. Link from the German guide to the shared API where needed.

API generation policy

The curated pages below api/ are edited manually. They document interfaces that applications should normally use and avoid repeating inherited methods for every concrete driver.

The complete reference is generated by sphinx.ext.apidoc according to apidoc_modules in docs/next/source/conf.py. Do not manually edit files below api/full; they may be replaced on the next clean build. Exclude legacy modules, generated version files, UI implementation modules, and other intentional internals in conf.py. Generated pages use no-index so the curated API remains the primary indexed definition.

Public docstrings are written in English. A new shared class, function, or exception belongs in a curated page when it is an intended extension point, frequently used by applications, or important for lifecycle and safety. Other public modules remain available through the complete reference.

tools/check_public_docstrings.py checks all importable modules and public classes, functions, and methods below src/mpylab independently of Sphinx. Private names, legacy modules, generated version data, and framework callbacks such as Qt slots, PLY grammar rules, and dynamically selected limit curves are intentionally excluded. The check has no baseline of accepted omissions: every new public interface must include an English docstring immediately.

For instrument drivers, the base class documents the common interface. A concrete driver does not need to repeat inherited methods such as Init, SetFreq, or GetData verbatim. The checker recognizes these overrides from the actual inheritance chain. Additional instrument-specific methods, new constructor parameters, and behavioral differences from the base class still require their own docstrings. This keeps the documentation consistent without copying the shared instrument behavior into every driver.

With --check-signatures, the tool also compares the Python signature and actual result paths with documented parameters and Returns or Yields sections. It recognizes existing reStructuredText and Google sections during the migration, but NumPy style rendered by sphinx.ext.napoleon is the target and requirement for new or changed interfaces.

python tools/check_public_docstrings.py --check-signatures

CI runs this complete check with tools/public_docstring_signature_baseline.json. The baseline records known signature gaps in the existing documentation component by component. A new public interface, a newly undocumented parameter, or a newly missing Returns or Yields section still fails the check. Improvements are always accepted and reduce the remaining migration debt.

python tools/check_public_docstrings.py \
    --signature-baseline tools/public_docstring_signature_baseline.json

Whenever a public method or its signature is changed, review and complete its docstring in NumPy style as part of the same change. Then update the baseline only to remove the resolved legacy gap. Do not add findings merely to make CI pass.

Figures and generated artifacts

Store maintained diagrams below docs/next/source/_static and reference them relative to the page. Prefer SVG for diagrams and plots where vector output is available. Every figure needs useful alternative text and a caption that explains its technical role. Do not commit the HTML build directory or generated api/full pages unless the publication process is deliberately changed to require them.

Examples must be runnable or derived from version-controlled virtual configurations. Do not embed workstation-specific absolute paths, private measurement data, or hardware credentials.

Review checklist

Before committing documentation changes, verify:

  • German and English pages have matching paths and synchronized content;

  • commands, API names, configuration keys, and output filenames match code;

  • new pages appear in a toctree and have useful cross-references;

  • specialist concepts have index or glossary entries where appropriate;

  • code examples state whether they require hardware;

  • changed public methods have had their parameters, result, and docstring reviewed together;

  • Sphinx succeeds with -W --keep-going -E -a;

  • check_public_docstrings.py, test_docs_next_structure.py, and git diff --check pass;

  • MIGRATION.md reflects completed migration work.

CI and publication

The create-pages job in .gitlab-ci.yml installs .[docs], verifies that Graphviz is available, and builds docs/next/source directly into public with warnings treated as errors. sphinx.ext.apidoc generates api/full during this build according to conf.py. The previous helper scripts tools/docs_generate_api.py and tools/docs_audit.py belong to the legacy publication path and are not run for the current documentation.

The test job runs tools/check_public_docstrings.py with the versioned signature baseline first. A new undocumented public Python interface and any new or worsened signature gap therefore fail the test stage rather than surfacing only during Sphinx publication.

No compatibility redirects are generated for old documentation URLs. The current information architecture is authoritative. Keep docs/source unchanged for one release cycle as a fallback, then remove it in a separate reviewed commit.

Historical material

Historical guides remain valuable but must not look like current operating instructions. They are stored in matching de/archive and en/archive pages with prominent historical notices and links to current replacements. Do not silently modernize a historical procedure; corrections belong in the current guide.

The completed migration state and URL decision are recorded in docs/next/MIGRATION.md outside the Sphinx source tree.