ADR 0013: A documentation site built from the README and the source¶
- Status: accepted (3.0.2). Asked for by the package owner on 2026-11-11.
Context¶
The README is the complete user guide (the owner's 600-line exemption), but it has no API reference, and the architecture notes and ADRs are loose Markdown files on GitHub. The owner wants the project documented to a professional standard: one site with the guide, a reference generated from the code, and the reasoning behind it.
Two facts constrain the tooling. The MetaTrader5 package is Windows-only,
while the docs are built on Linux. And the package root has no static
__all__: unknown names resolve lazily through MetaTrader5 (ADR 0010).
Decision¶
- MkDocs with Material for MkDocs and mkdocstrings, published to GitHub Pages at https://akinzou.github.io/MetaTrader5-Python/.
- The reference is read statically by griffe, never imported. It lists
each public name explicitly (
PythonMetaTrader5.<name>), not the package, so theMetaTrader5namespace never leaks into it.tests/unit/test_api_reference.pyfails when a public name has no entry or no docstring, a public method has no docstring, or anErrorKindmember does not say what it means. - The README stays the single source of the guide.
docs/guide.mdmarkers, which PyPI and GitHub do not render.MIGRATION.mdandCHANGELOG.mdare included the same way. The guide is one page so that the README's in-page links keep working; its links to other documents still point to GitHub, as on PyPI. mkdocs build --strictruns on every pull request, in the workflow that deploys, so the build checked on a pull request is the one published. A broken link or anchor, a missing include, or a page left out of the navigation fails it.- The site is deployed from master by
.github/workflows/docs.yml, with the official Pages actions; GitHub Pages is set to the Actions source.
We chose MkDocs over Sphinx because Sphinx autodoc imports the package: on
Linux that needs autodoc_mock_imports for MetaTrader5, and automodule
would follow the computed __all__ into hundreds of MT5 names. The Markdown
documents would also need MyST. sphinx-autoapi avoids the import, but not
the second toolchain.
We chose including the README over moving its text into the site because two copies of the guide would drift, and the owner wants PyPI to show the complete guide.
We chose deploying from master over deploying from the release tag because a
tag-only site could not ship before the next release, and a fix to the docs
would wait for one too. The cost: the site can describe changes not yet on
PyPI. The changelog's Unreleased section names them.
Rejected: Zensical, the successor of Material for MkDocs. At 0.1 its mkdocstrings support is preliminary.
Consequences¶
- Material for MkDocs is in maintenance mode and MkDocs 1.6 gets no new
features. The configuration uses no custom hooks and no plugins besides
search and mkdocstrings, because Zensical reads
mkdocs.ymland every extra plugin would make moving there harder. - Docstrings are now user-facing text. They state the contract briefly; the
semantics and examples stay in the guide.
trader.pyandbroker.pyare close to the 300-line limit, and parameter tables there would push them over. - The
docsextra installs the toolchain:pip install -e ".[docs]", thenmkdocs serve. - The 2.x
Brokeris documented as a class only, pointing to the migration guide.