Machine-readable documentation builds#
The documentation workflow renders selected canonical Sphinx pages with
sphinx-markdown-builder after the HTML build, then runs
docs/build_agent_docs.py. The resulting llms.txt and Markdown siblings live
inside the same version directory as their HTML pages. Nothing is written to the
generated hosting repository by this script.
The curated index covers installation, model selection, API conventions, two model references, tutorials and citation. It is not a complete Markdown mirror. Each exported page identifies the package version, documentation URL and exact source commit. Internal document links deliberately point to HTML so that pages outside this selection remain accessible. A small translator adapter preserves HTML image paths, bibliography anchors and gallery navigation, and omits raw HTML scripts/styles. Other unsupported nodes retain the converter’s warnings rather than being silently accepted. Interactive tables and custom Sphinx content may not survive Markdown conversion; follow the canonical HTML link.
Build and validation#
After a successful normal HTML build, run from the repository root:
sphinx-build -b markdown -d docs/_build/doctrees -D plot_gallery=0 docs docs/_build/markdown
python docs/build_agent_docs.py \
--markdown-root docs/_build/markdown \
--html-root docs/_build/html \
--site-url https://braindecode.org/dev/ \
--version "$(python -c 'import braindecode; print(braindecode.__version__)')" \
--revision "$(git rev-parse HEAD)"
Use a clean output directory for each source revision. The Markdown pass disables example execution; the preceding normal HTML build still has its usual dataset and model requirements. Publication fails if any curated HTML or Markdown page is missing or its Markdown is empty. Offline tests require pytest, Sphinx, sphinx-markdown-builder, sphinx-gallery, sphinx-design, sphinxcontrib-bibtex and matplotlib. The integration fixture builds HTML then Markdown with shared doctrees and checks that its tiny, data-free example executes only once:
python -m pytest -q docs/tests/test_agent_docs.py
Deployment scope#
The existing master-push workflow deploys only dev/. A development checkout can
contain a release-looking package version; the URL scope and source commit are therefore
essential provenance. This change does not create a root index, retarget stable/ or
rebuild any historical version. A future release build must use its own source checkout,
matching HTML and explicit version URL; do not copy development Markdown into stable
documentation.