Skip to content

Add a navigable and audited Backtest User Guide - #121

Merged
stefan-jansen merged 6 commits into
mainfrom
docs/complete-user-guide
Sep 24, 2026
Merged

stefan-jansen merged 6 commits into
mainfrom
docs/complete-user-guide

Conversation

@stefan-jansen

@stefan-jansen stefan-jansen commented Sep 24, 2026 •

Copy link
Copy Markdown
Contributor

Why

The 0.1.9 documentation release has a User Guide tab but no overview page or clear path from the Book Guide. The homepage also contains a run_backtest example with undefined names. The Results guide's HTML tearsheet example uses an undefined value and omits its visualization dependency. This PR is the first corrective pass for #120.

Changes

  • Add /user-guide/ with task and asset-setting routes to the existing topic pages and complete tutorials; link it from the homepage and Book Guide.
  • Replace the broken homepage snippet with a complete, checked run_backtest example.
  • Replace the Results tearsheet snippet with a complete example using ml4t-diagnostic[viz]==0.1.4; run it against the installed wheel in CI and release verification.
  • State prerequisites for contextual snippets on each topic page and remove unsupported absolute claims about framework matching, vectorization, and test counts.

Verification

  • uv run mkdocs build --strict passed. The rendered guide link checker resolved 2,005 content links, including page and section anchors, and checked 29 external destinations. It now runs in PR CI and the docs workflow.
  • The Book Guide checker resolved 22 companion paths at its pinned revision.
  • Twelve documentation contract tests and pre-commit run --all-files passed.
  • A fresh Python 3.12 environment installed the built 0.1.10.dev3+gb2d2702df wheel and ran every default documentation example. After installing ml4t-diagnostic[viz]==0.1.4, the diagnostic handoff and full HTML tearsheet examples passed.
  • A static audit parsed every User Guide Python block and found no missing public Broker, DataFeed, Result, or OrderType member names and no unknown BacktestConfig keywords. Contextual fragments remain labeled with their prerequisites; this audit does not establish every prose claim.

Issue #120 remains open until the reviewed guide is merged, deployed, and checked at the canonical route. This PR should not be read as a claim of 100% documentation correctness.

The published guide lacked a direct overview, and the homepage convenience example referenced undefined names. Link the existing task pages and verify a complete example against the documentation checker.
The old result guide referenced an undefined analysis variable and omitted the visualization dependency. Run a complete HTML tearsheet example against the installed wheel in CI and release verification.
Explain the prerequisites for reference snippets on each topic page. Remove absolute claims about framework equivalence, vectorization, and an incorrect test count.
Copilot AI lite review requested due to automatic review settings September 24, 2026 09:49

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

@stefan-jansen
stefan-jansen merged commit 34ac727 into main Sep 24, 2026
43 checks passed
@stefan-jansen
stefan-jansen deleted the docs/complete-user-guide branch September 24, 2026 10:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants