.. index:: documentation maintenance, Sphinx build, documentation publication 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: .. code-block:: console 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: .. code-block:: console 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: .. code-block:: console 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. Navigation, cross-references, and index --------------------------------------- Place a page according to its primary purpose: task entry, measurement, framework, configuration, results, or help. Link it from the nearest section index and add contextual cross-references from related workflows. A page that is only reachable through several generic index pages is not sufficiently discoverable. Use ``:doc:`` for pages, ``:class:``, ``:func:``, and ``:mod:`` for Python objects, and ``:ref:`` for named targets and the generated ``genindex``. Add ``.. index::`` entries for important specialist terms. Add stable concepts to the bilingual glossary, taking care that Sphinx glossary terms share a global namespace across both languages. 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. .. code-block:: console 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. .. code-block:: console 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.