From f4d48396521e4c9a8995b02e0178e5c570c94d0b Mon Sep 17 00:00:00 2001
From: Wiktor Jelen <35398584+Akinzou@users.noreply.github.com>
Date: Wed, 11 Nov 2026 16:02:37 +0100
Subject: [PATCH] docs: documentation site with an API reference, built from
the README and the source
MkDocs + Material + mkdocstrings, published to GitHub Pages (ADR 0013).
- The user guide is the README itself, included between snippet markers that
PyPI and GitHub do not render: one source, no second copy to drift.
- The API reference is read statically by griffe, never imported, and lists
each public name explicitly, so the Windows-only MetaTrader5 package and the
computed __all__ never reach it.
- Docstrings on every public name and method, and on each ErrorKind member.
tests/unit/test_api_reference.py fails on a public name without a reference
entry or docstring.
- .github/workflows/docs.yml builds with --strict on every pull request and
deploys the same build from master; broken links, anchors, includes and
pages left out of the navigation fail it.
Chose MkDocs over Sphinx because autodoc imports the package, which needs
MetaTrader5 mocked on Linux and follows the computed __all__ into the whole
MT5 namespace. Chose one workflow for check and deploy over a job in ci.yml,
because two copies of the build would drift apart.
---
.github/workflows/docs.yml | 63 ++++++++
.gitignore | 3 +
CHANGELOG.md | 10 ++
README.md | 21 ++-
docs/CHANGELOG.md | 1 +
docs/MIGRATION.md | 1 +
docs/adr/0013-documentation-site.md | 70 +++++++++
docs/adr/index.md | 11 ++
docs/assets/favicon.svg | 1 +
docs/guide.md | 8 +
docs/index.md | 88 +++++++++++
docs/reference/index.md | 18 +++
docs/reference/legacy.md | 9 ++
docs/reference/market.md | 11 ++
docs/reference/orders.md | 9 ++
docs/reference/results.md | 17 +++
docs/reference/trading.md | 11 ++
mkdocs.yml | 138 ++++++++++++++++++
pyproject.toml | 14 +-
.../application/execution.py | 9 ++
src/PythonMetaTrader5/application/trader.py | 10 ++
src/PythonMetaTrader5/domain/errors.py | 36 ++++-
src/PythonMetaTrader5/domain/inputs.py | 1 +
src/PythonMetaTrader5/domain/market.py | 11 ++
src/PythonMetaTrader5/domain/orders.py | 5 +
src/PythonMetaTrader5/domain/stops.py | 22 +++
src/PythonMetaTrader5/legacy/broker.py | 5 +
src/PythonMetaTrader5/result.py | 9 ++
tests/unit/test_api_reference.py | 64 ++++++++
29 files changed, 668 insertions(+), 8 deletions(-)
create mode 100644 .github/workflows/docs.yml
create mode 100644 docs/CHANGELOG.md
create mode 100644 docs/MIGRATION.md
create mode 100644 docs/adr/0013-documentation-site.md
create mode 100644 docs/adr/index.md
create mode 100644 docs/assets/favicon.svg
create mode 100644 docs/guide.md
create mode 100644 docs/index.md
create mode 100644 docs/reference/index.md
create mode 100644 docs/reference/legacy.md
create mode 100644 docs/reference/market.md
create mode 100644 docs/reference/orders.md
create mode 100644 docs/reference/results.md
create mode 100644 docs/reference/trading.md
create mode 100644 mkdocs.yml
create mode 100644 tests/unit/test_api_reference.py
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
new file mode 100644
index 0000000..a40c349
--- /dev/null
+++ b/.github/workflows/docs.yml
@@ -0,0 +1,63 @@
+name: Docs
+
+# Built strictly on every pull request; deployed from master, not from the
+# release tag (ADR 0013): a fix to the docs should not wait for a release. The
+# changelog's Unreleased section names what the site describes but PyPI does
+# not have yet. One workflow for both, so the build a pull request checks is
+# the build master publishes.
+on:
+ pull_request:
+ push:
+ branches: [master]
+ workflow_dispatch:
+
+permissions:
+ contents: read
+
+concurrency:
+ group: docs-${{ github.ref }}
+ cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+ build:
+ # Strict: a broken link or anchor, a missing README include or a page left
+ # out of the navigation fails. Linux on purpose: it proves the reference
+ # never imports the Windows-only MetaTrader5 package.
+ name: documentation site (mkdocs --strict)
+ runs-on: ubuntu-latest
+ steps:
+ # Actions are pinned to commit SHAs: a moved tag cannot inject code into CI.
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+ with:
+ persist-credentials: false
+ - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+ with:
+ python-version: "3.12"
+ - run: python -m pip install ".[docs]"
+ - run: mkdocs build --strict
+ env:
+ NO_MKDOCS_2_WARNING: "1"
+ - if: github.event_name != 'pull_request'
+ uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+ with:
+ path: site
+
+ deploy:
+ name: publish to GitHub Pages
+ needs: build
+ # A pull request or a manual run from a branch must not replace the site.
+ if: github.event_name != 'pull_request' && github.ref == 'refs/heads/master'
+ # One deployment at a time, and a running one is never cancelled half-way.
+ concurrency:
+ group: pages
+ cancel-in-progress: false
+ runs-on: ubuntu-latest
+ permissions:
+ pages: write
+ id-token: write
+ environment:
+ name: github-pages
+ url: ${{ steps.deployment.outputs.page_url }}
+ steps:
+ - id: deployment
+ uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1
diff --git a/.gitignore b/.gitignore
index b240fa3..b4a70b2 100644
--- a/.gitignore
+++ b/.gitignore
@@ -13,6 +13,9 @@ __pycache__/
coverage.xml
htmlcov/
+# Documentation build output (mkdocs build)
+site/
+
# Local environments and secrets
.venv/
.env
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e945b40..39dbc16 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,16 @@ All notable changes to this project are documented here. The format follows
## [Unreleased]
+### Added
+- Documentation site at : the
+ README as the user guide, an API reference generated from the source, the
+ architecture overview, every ADR, the migration guide and this changelog
+ (ADR 0013). Built with `mkdocs build --strict` on every pull request and
+ deployed from master. `pip install -e ".[docs]"` installs the toolchain.
+- Docstrings on every public name and method, and on each `ErrorKind` member
+ saying what it means. A test fails when a public name has no reference entry
+ or no docstring.
+
## [3.0.1] - 2026-11-09
### Fixed
diff --git a/README.md b/README.md
index 53ba470..63263a5 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,7 @@
# PythonMetaTrader5
[](https://github.com/Akinzou/MetaTrader5-Python/actions/workflows/ci.yml)
+[](https://akinzou.github.io/MetaTrader5-Python/)
[](https://pypi.org/project/PythonMetaTrader5/)


@@ -46,14 +47,18 @@ the release you are reading (ADR 0012). On PyPI the Contents entries
above do not jump to their sections; read this page on
[GitHub](https://github.com/Akinzou/MetaTrader5-Python/blob/master/README.md#contents) for that.
+Documentation site, with this guide, the API reference, the architecture and
+every ADR: .
+
Other documents: [CHANGELOG.md](https://github.com/Akinzou/MetaTrader5-Python/blob/master/CHANGELOG.md) ·
[MIGRATION.md](https://github.com/Akinzou/MetaTrader5-Python/blob/master/MIGRATION.md) · [docs/architecture.md](https://github.com/Akinzou/MetaTrader5-Python/blob/master/docs/architecture.md) ·
[docs/adr](https://github.com/Akinzou/MetaTrader5-Python/tree/master/docs/adr)
+
## Why this library
-- **Every trading call returns.** Requotes are retried a bounded number of times
- with a fresh quote; everything else comes back immediately as a typed error.
+- **Every trading call returns.** Requotes and missing quotes are retried a
+ bounded number of times with a fresh quote; everything else comes back immediately as a typed error.
(The deprecated `Broker.login(ToEffect=True)` is the one exception: as in
2.x, it keeps trying until the login works.)
- **No silent defaults.** Values that MT5 would quietly read as something else
@@ -99,6 +104,7 @@ To stay on the old API: `pip install "PythonMetaTrader5<3"`.
## Quick start
+
```python
from PythonMetaTrader5 import Err, Ok, Side, Stop, connect
@@ -123,6 +129,7 @@ with trader: # shuts the terminal connection down on exit
trader.close_positions("EURUSD") # only this bot's (magic 1001) positions
```
+
## Connecting
@@ -429,6 +436,7 @@ to MetaTrader 5. Details: [docs/architecture.md](https://github.com/Akinzou/Meta
| [0010](https://github.com/Akinzou/MetaTrader5-Python/blob/master/docs/adr/0010-keep-the-metatrader5-re-export.md) | Keep re-exporting the MetaTrader5 namespace, lazily |
| [0011](https://github.com/Akinzou/MetaTrader5-Python/blob/master/docs/adr/0011-close-all-defaults-to-own-magic.md) | Close-all and cancel-all default to the trader's own magic |
| [0012](https://github.com/Akinzou/MetaTrader5-Python/blob/master/docs/adr/0012-pin-readme-links-at-publish.md) | Publish from the tag and pin the README's links there |
+| [0013](https://github.com/Akinzou/MetaTrader5-Python/blob/master/docs/adr/0013-documentation-site.md) | A documentation site built from the README and the source |
## Development
@@ -441,6 +449,14 @@ pytest --cov
python scripts/check_file_length.py
```
+The documentation site (ADR 0013) includes this README as its user guide:
+
+```bash
+pip install -e ".[docs]"
+mkdocs serve # preview at http://127.0.0.1:8000
+mkdocs build --strict # what CI runs: broken links and anchors fail
+```
+
`tests/contract` compares the unit-test fakes with the installed `MetaTrader5`
package and is skipped where it is not installed (anywhere but Windows).
Integration tests trade on a **demo** account and are skipped unless
@@ -455,3 +471,4 @@ tag and refuses to run from any other ref (ADR 0012).
[CC BY-NC 4.0](https://github.com/Akinzou/MetaTrader5-Python/blob/master/LICENSE). Trading carries risk; this software comes without any
warranty.
+
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
new file mode 100644
index 0000000..786b75d
--- /dev/null
+++ b/docs/CHANGELOG.md
@@ -0,0 +1 @@
+--8<-- "CHANGELOG.md"
diff --git a/docs/MIGRATION.md b/docs/MIGRATION.md
new file mode 100644
index 0000000..0fe9b55
--- /dev/null
+++ b/docs/MIGRATION.md
@@ -0,0 +1 @@
+--8<-- "MIGRATION.md"
diff --git a/docs/adr/0013-documentation-site.md b/docs/adr/0013-documentation-site.md
new file mode 100644
index 0000000..5d4d1ed
--- /dev/null
+++ b/docs/adr/0013-documentation-site.md
@@ -0,0 +1,70 @@
+# ADR 0013: A documentation site built from the README and the source
+
+- Status: accepted (after 3.0.1, unreleased). 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 .
+- **The reference is read statically** by griffe, never imported. It lists
+ each public name explicitly (`::: PythonMetaTrader5.`), not the
+ package, so the `MetaTrader5` namespace never leaks into it.
+ `tests/unit/test_api_reference.py` fails when a public name has no entry or
+ no docstring, a public method has no docstring, or an `ErrorKind` member does
+ not say what it means.
+- **The README stays the single source of the guide.** `docs/guide.md`
+ includes it between `` and `[end:guide]`
+ markers, which PyPI and GitHub do not render. `MIGRATION.md` and
+ `CHANGELOG.md` are 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 --strict` runs 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.yml` and 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.py` and `broker.py` are
+ close to the 300-line limit, and parameter tables there would push them over.
+- The `docs` extra installs the toolchain: `pip install -e ".[docs]"`, then
+ `mkdocs serve`.
+- The 2.x `Broker` is documented as a class only, pointing to the migration
+ guide.
diff --git a/docs/adr/index.md b/docs/adr/index.md
new file mode 100644
index 0000000..dd39cc4
--- /dev/null
+++ b/docs/adr/index.md
@@ -0,0 +1,11 @@
+# Architecture decision records
+
+Each record explains one decision that shapes how the library behaves: the
+context, what was decided, the alternatives that were rejected and why, and
+the consequences. They are the reasoning behind the rules in the
+[user guide](../guide.md); read one when a behaviour looks surprising.
+
+A record is never rewritten to match a later decision. A new record supersedes
+it, so the history of why the library works this way stays readable. The
+[architecture overview](../architecture.md) shows where each decision lives in
+the code.
diff --git a/docs/assets/favicon.svg b/docs/assets/favicon.svg
new file mode 100644
index 0000000..e95e66f
--- /dev/null
+++ b/docs/assets/favicon.svg
@@ -0,0 +1 @@
+
diff --git a/docs/guide.md b/docs/guide.md
new file mode 100644
index 0000000..c97debe
--- /dev/null
+++ b/docs/guide.md
@@ -0,0 +1,8 @@
+---
+hide:
+ - navigation
+---
+
+# User guide
+
+--8<-- "README.md:guide"
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..44cec79
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,88 @@
+---
+hide:
+ - navigation
+ - toc
+---
+
+# PythonMetaTrader5
+
+A safe, typed trading layer over the official
+[`MetaTrader5`](https://pypi.org/project/MetaTrader5/) Python package, built
+for bots where a trading call must **never hang, never retry blindly, and
+never fail silently**.
+
+[Get started](guide.md#quick-start){ .md-button .md-button--primary }
+[API reference](reference/index.md){ .md-button }
+[Architecture](architecture.md){ .md-button }
+
+```bash
+pip install PythonMetaTrader5
+```
+
+
+
+- :material-timer-check-outline:{ .lg .middle } **Every call returns**
+
+ ---
+
+ Requotes and missing quotes are retried a bounded number of times with a
+ fresh quote. Everything else comes back at once as a typed error.
+
+ [:octicons-arrow-right-24: Retries](guide.md#retries)
+
+- :material-content-duplicate:{ .lg .middle } **No double fills**
+
+ ---
+
+ Timeouts and lost connections are never retried: the order may already be
+ live. They come back as `OUTCOME_UNKNOWN`.
+
+ [:octicons-arrow-right-24: Error kinds](guide.md#error-kinds)
+
+- :material-shield-check-outline:{ .lg .middle } **No silent defaults**
+
+ ---
+
+ Values MT5 would quietly read as something else, such as `sl=0` or
+ `ticket=0`, are refused before anything is sent.
+
+ [:octicons-arrow-right-24: ADR 0008](adr/0008-refuse-values-mt5-misreads.md)
+
+- :material-code-braces:{ .lg .middle } **Typed results**
+
+ ---
+
+ `Ok(receipt)` or `Err(TradeError)` with an `ErrorKind` instead of magic
+ numbers, checked by mypy and your editor.
+
+ [:octicons-arrow-right-24: Results and errors](guide.md#results-and-errors)
+
+- :material-robot-outline:{ .lg .middle } **Close-all touches only your bot**
+
+ ---
+
+ `close_positions()` and `cancel_pending_orders()` act on the trader's own
+ magic number unless told otherwise.
+
+ [:octicons-arrow-right-24: Magic numbers](guide.md#magic-numbers-whose-trades-a-call-touches)
+
+- :material-sitemap-outline:{ .lg .middle } **Built to be reasoned about**
+
+ ---
+
+ Clean Architecture with ports and adapters, and every non-obvious choice
+ recorded as a decision record.
+
+ [:octicons-arrow-right-24: Decisions](adr/index.md)
+
+