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)
+
+