Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 63 additions & 0 deletions .github/workflows/docs.yml
Original file line number Diff line number Diff line change
@@ -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
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,9 @@ __pycache__/
coverage.xml
htmlcov/

# Documentation build output (mkdocs build)
site/

# Local environments and secrets
.venv/
.env
10 changes: 10 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,16 @@ All notable changes to this project are documented here. The format follows

## [Unreleased]

### Added
- Documentation site at <https://akinzou.github.io/MetaTrader5-Python/>: 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
Expand Down
21 changes: 19 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
# PythonMetaTrader5

[![CI](https://github.com/Akinzou/MetaTrader5-Python/actions/workflows/ci.yml/badge.svg)](https://github.com/Akinzou/MetaTrader5-Python/actions/workflows/ci.yml)
[![Docs](https://img.shields.io/badge/docs-online-blue?logo=materialformkdocs&logoColor=white)](https://akinzou.github.io/MetaTrader5-Python/)
[![PyPI](https://img.shields.io/pypi/v/pythonmetatrader5)](https://pypi.org/project/PythonMetaTrader5/)
![Python](https://img.shields.io/badge/python-3.10%2B-blue?logo=python&logoColor=white)
![License](https://img.shields.io/badge/license-CC_BY--NC_4.0-lightgrey.svg)
Expand Down Expand Up @@ -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: <https://akinzou.github.io/MetaTrader5-Python/>.

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)

<!-- --8<-- [start:guide] -->
## 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
Expand Down Expand Up @@ -99,6 +104,7 @@ To stay on the old API: `pip install "PythonMetaTrader5<3"`.

## Quick start

<!-- --8<-- [start:quickstart] -->
```python
from PythonMetaTrader5 import Err, Ok, Side, Stop, connect

Expand All @@ -123,6 +129,7 @@ with trader: # shuts the terminal connection down on exit

trader.close_positions("EURUSD") # only this bot's (magic 1001) positions
```
<!-- --8<-- [end:quickstart] -->

## Connecting

Expand Down Expand Up @@ -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

Expand All @@ -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
Expand All @@ -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.
<!-- --8<-- [end:guide] -->
1 change: 1 addition & 0 deletions docs/CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
--8<-- "CHANGELOG.md"
1 change: 1 addition & 0 deletions docs/MIGRATION.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
--8<-- "MIGRATION.md"
70 changes: 70 additions & 0 deletions docs/adr/0013-documentation-site.md
Original file line number Diff line number Diff line change
@@ -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 <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 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 `<!-- --8<-- [start:guide] -->` 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.
11 changes: 11 additions & 0 deletions docs/adr/index.md
Original file line number Diff line number Diff line change
@@ -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.
1 change: 1 addition & 0 deletions docs/assets/favicon.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
8 changes: 8 additions & 0 deletions docs/guide.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
---
hide:
- navigation
---

# User guide

--8<-- "README.md:guide"
88 changes: 88 additions & 0 deletions docs/index.md
Original file line number Diff line number Diff line change
@@ -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
```

<div class="grid cards" markdown>

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

</div>

## At a glance

--8<-- "README.md:quickstart"

!!! warning "Before trading real money"

Run your bot on a demo account first, give it its own `magic`, and treat
`OUTCOME_UNKNOWN` as "maybe filled". The full checklist is in the
[user guide](guide.md#before-trading-real-money).
18 changes: 18 additions & 0 deletions docs/reference/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
# API reference

Everything below is importable from the package root:

```python
from PythonMetaTrader5 import connect, Trader, Stop, Ok, Err, ErrorKind
```

Generated from the source and its type hints. The behaviour behind each call,
with examples, is in the [user guide](../guide.md).

| Page | Contents |
|---|---|
| [Connecting and trading](trading.md) | `connect`, `Trader`, `RetryPolicy`, `ANY_MAGIC`, `AnyMagic` |
| [Orders and stops](orders.md) | `Side`, `Stop`, `StopKind`, `PendingKind` |
| [Results and errors](results.md) | `Result`, `Ok`, `Err`, `TradeError`, `ErrorKind`, `BatchFailure` |
| [Account state](market.md) | `Position`, `PendingOrder`, `TradeReceipt`, `Tick` |
| [2.x Broker (deprecated)](legacy.md) | `Broker` |
9 changes: 9 additions & 0 deletions docs/reference/legacy.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
# 2.x Broker (deprecated)

`Broker` keeps 2.x bots running and emits a `DeprecationWarning`. Several 2.x
behaviours were unsafe and changed; the [migration guide](../MIGRATION.md)
lists each one and maps the main `Broker` calls to `Trader`.

::: PythonMetaTrader5.Broker
options:
members: false
11 changes: 11 additions & 0 deletions docs/reference/market.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# Account state

Read models returned by `Trader` queries and trading calls.

::: PythonMetaTrader5.Position

::: PythonMetaTrader5.PendingOrder

::: PythonMetaTrader5.TradeReceipt

::: PythonMetaTrader5.Tick
Loading
Loading