Repository navigation
Complete and audit the Backtest User Guide #120
Description
User problem
The published site has 12 topic pages under a User Guide navigation tab, but no User Guide overview or task path. The Book Guide is a notebook cross-reference, not the user guide. The prior documentation milestone added executable tutorials but did not audit the older guide code blocks against the released package. A reader can copy an incomplete homepage example that refers to undefined prices and BuyAndHold.
Reproduction
Extract the run_backtest code block after the homepage quick example and execute it as shown. It raises NameError: name 'prices' is not defined; BuyAndHold is also undefined. The block was outside the installed-wheel documentation check.
Acceptance
- Give the User Guide a direct overview URL and a clear route from the homepage and Book Guide. Separate tutorials, task guides, explanations, and API reference by reader purpose.
- Audit all published User Guide and homepage code blocks. Runnable examples must execute against the built wheel with checked output where they print results. Deliberately partial snippets must say what they assume and link to a complete runnable example. Fix wrong or obsolete API claims rather than marking them partial.
- Cover the user workflow from prepared data and signals through strategy, orders, account/risk/cost settings, multi-asset sessions, result exports, and downstream analysis. Include equity, ETF, futures, FX, and crypto perpetual variants where the settings differ.
- Explain unsupported cases and required optional dependencies at the point of use. Tie book notebook links to checked paths and state what each adds.
- Keep API reference generated from the released public surface. Add behavioral checks for claims that depend on lifecycle, order timing, cash, funding, or result schemas.
- Verify strict site build, links, clean-wheel examples, relevant tests, and deployed version/commit identity before claiming completion.
The guide should meet the standard of a reader being able to find a task, run its complete example, inspect the result, and then look up the exact API contract without an undefined name or undocumented prerequisite.
Activity
stefan-jansen commentedon Sep 24, 2026
PR #121 adds the missing User Guide overview and routes from the homepage and Book Guide. It replaces two broken or incomplete public examples with complete installed-wheel checks, states prerequisites for contextual snippets, and narrows unsupported claims found during the audit.
The strict MkDocs build, 22 pinned book links, 12 documentation contract tests, pre-commit checks, a clean Python 3.12 wheel run of the full tutorial set, and optional diagnostic/HTML tearsheet runs passed locally. All 43 remote PR checks passed or took their documented skip. The issue remains open until the PR is approved, merged, and the corrected guide is deployed and verified at the canonical route.
docs: complete and verify Backtest User Guide
stefan-jansen commentedon Sep 24, 2026
The v0.1.11 guide is deployed and the initial broken-block correction is complete. I am continuing this issue under the documentation-quality handoff: inventorying principal workflows against task routes, released API reference, wheel-run examples, and book examples; checking the pinned companion notebooks for actual API use; and adding a bounded Zipline migration guide. I will retain strict build, link, and clean-wheel checks and report any unsupported workflows explicitly in the PR. This issue remains open until that follow-up is reviewed.
stefan-jansen commentedon Sep 24, 2026
PR #123 was squash-merged into public
mainas672804b36915742fe18af9cd09b44e9839d39d6fafter 42 successful checks and one documented skip. The post-merge Docs workflow succeeded and retained the commit-bound site artifact: https://github.com/ml4t/backtest/actions/runs/36041265186.The live User Guide still identifies v0.1.11 at
6a1974bd55c5ee362d33bcd008121bfaff370dbf. This issue remains open until the updated guide is published to the canonical route and its deployed version and commit are verified. The merged PR records the capability inventory, 34 clean-wheel examples, 22 pinned book paths, and the expanded rendered-link gate.stefan-jansen commentedon Sep 24, 2026
Completed in PR #123 (squash commit
672804b36915742fe18af9cd09b44e9839d39d6f) and released as v0.1.12.The release workflow passed release candidate CI, ecosystem qualification, licensed comparisons, documentation deployment, PyPI publication, and post-release verification. The deployed canonical guide, User Guide, quickstart, and API page each independently identify version
0.1.12and that commit. PyPI lists the wheel and source distribution.Documentation verification for PR #123 included 34 clean-wheel examples, 146 bound public API calls, strict MkDocs, 22 pinned book paths, 8,422 rendered content links across the full site, and 33 external guide destinations. The rendered internal link check runs in CI. Book notebooks were inspected for their stated roles and paths, but were not executed as installed-wheel examples because they use book datasets and dependencies.