Last Updated: 2026-05-04 Owner: Docs-Dev Summary: Reference guide for why the QuantMatrix MkDocs site exists, how it is stored, versioned, built, deployed, and accessed locally.

QuantMatrix MkDocs Platform Guide¶

This document explains the documentation platform itself.

Use it when you want to understand: - why MkDocs was added to the project - how the docs are stored in the repository - how documentation versioning currently works - how the docs site is built and deployed - how to start the application locally - how to access both the docs site and the application UI

1. Purpose¶

The QuantMatrix documentation set started as individual Markdown and PDF files plus a custom local HTML portal.

MkDocs was added to give the project a more durable documentation platform with: - a searchable HTML site - structured left navigation - section and subsection organization - easier maintenance as the docs set grows - a cleaner path to free static hosting

In short, MkDocs is the long-term documentation surface, while Markdown files in documentation/docs/ remain the source of truth.

2. Why This Project Uses MkDocs¶

MkDocs is a good fit for QuantMatrix because: - the documentation set is already Markdown-based - the project needs a searchable internal knowledge base - the docs need to be easy to edit in the repository - the site should be previewable locally before publishing - static-site hosting is simple and inexpensive

Material for MkDocs is layered on top to provide: - better navigation - better search - light and dark theme support - better code block usability

3. Repository Storage Model¶

The current repository layout for the documentation platform is:

documentation/docs/                         source Markdown documents
documentation/mkdocs.yml      MkDocs site configuration
documentation/requirements-docs.txt
                              docs-only Python dependencies
documentation/site/         generated MkDocs build output
.github/workflows/docs-site.yml
                              GitHub Pages build and deploy workflow
documentation/portal/         legacy local HTML portal kept during transition
documentation/tools/build_docs_catalog.py   metadata-based catalog generator
documentation/tools/build_docs_portal.py    legacy portal bundle generator

Source of Truth¶

The source of truth is: - the Markdown files inside documentation/docs/

Generated artifacts such as: - PDF mirrors - the documentation/site/ output - the legacy portal bundle

should all be treated as derived outputs.

4. How Documentation Versioning Works¶

Current Versioning Model¶

Right now, documentation versioning is repository-based: - the docs live in Git alongside the application code - every documentation change is versioned through normal repository history - the Last Updated field gives quick reader-facing freshness - the Summary, Tags, and Owner fields improve discoverability and maintenance

This means the current versioning model is: - simple - source-controlled - easy to review in pull requests

Current State¶

There is not yet a multi-version published docs site such as: - v1 - v2 - live - paper

That is intentional for now. The project is still in an early build and alignment phase.

When Richer Versioning Should Be Added¶

Formal documentation versioning becomes useful when: - the API starts changing between releases - the live system diverges materially from the paper-trading system - multiple teams need stable references for different releases

If that becomes necessary later, the likely next step is: - add MkDocs versioning with a tool such as mike

5. Metadata Model¶

Each maintained Markdown document should include:

Title: ...
Tags: ...
Last Updated: YYYY-MM-DD
Owner: ...
Summary: ...

These fields are used to support: - catalog generation - better search quality - ownership clarity - easier maintenance reviews

6. How The MkDocs Site Is Created¶

The site is defined by: - mkdocs.yml - the Markdown files in documentation/docs/

The current setup includes: - Material theme - search plugin - grouped navigation - metadata parsing - a docs landing page - contributor workflow docs - changelog and style guide

Main Setup Files¶

documentation/mkdocs.yml
documentation/requirements-docs.txt
documentation/docs/index.md
.github/workflows/docs-site.yml

7. How The Site Is Built Locally¶

Install Docs Dependencies¶

Use the docs dependency file:

python -m pip install -r documentation/requirements-docs.txt

Build The Site¶

Run:

mkdocs build -f documentation/mkdocs.yml --strict

What this does: - reads Markdown from documentation/docs/ - applies the navigation and theme from documentation/mkdocs.yml - validates the site build strictly - writes the built HTML output into documentation/site/

Local Preview¶

Run:

mkdocs serve -f documentation/mkdocs.yml -a 127.0.0.1:8011

Then open:

http://127.0.0.1:8011/quantmatrix/

This is the current local docs preview URL used in this workspace.

8. How The Site Is Deployed¶

The deployment scaffold is already present in:

.github/workflows/docs-site.yml

Deployment Model¶

The workflow is designed for GitHub Pages:

checkout repository
install Python
install docs dependencies from documentation/requirements-docs.txt
run mkdocs build -f documentation/mkdocs.yml --strict
upload the generated documentation/site/ directory
deploy to GitHub Pages

Triggering¶

The workflow currently triggers on: - pushes to main - changes to docs-related files - manual workflow dispatch

What Is Still Needed For Full Publishing¶

To complete hosted publishing, the repository still needs: - a real GitHub repository URL in documentation/mkdocs.yml - GitHub Pages enabled for the repository - a real production site_url

9. Legacy Portal Status¶

The repository still contains: - documentation/portal/

That older portal remains available during the transition, but MkDocs is the preferred future direction.

The legacy portal is still useful because: - it provides continuity during the migration - it offers a second local surface for docs browsing

10. How The Application Is Started¶

There are two common local application paths.

Option A: Demo Mode Without Docker¶

Use this when you want the UI quickly without external dependencies:

python -m pip install -e .
python -m trading_system.demo

This starts the local demo application at:

http://127.0.0.1:8000

Option B: Local Python App With Runtime Engine¶

Use this when the full local app flow is configured:

python -m trading_system.local

By default, the local application also serves on:

http://127.0.0.1:8000

The exact host and port come from application settings, with 8000 as the current default.

11. How The Application Is Accessed¶

Documentation Site¶

Current local docs URL:

http://127.0.0.1:8011/quantmatrix/

Application UI¶

Current local app URL:

http://127.0.0.1:8000

This separation is intentional: - docs run on 8011 - app UI runs on 8000

12. Recommended Operating Model¶

For day-to-day work, use this pattern:

edit Markdown inside documentation/docs/
update metadata fields when needed
rebuild the documentation catalog if metadata or inventory changed
preview locally with MkDocs
keep the application and docs URLs distinct
publish through GitHub Pages once the repository hosting is fully configured

13. Current State vs Target State¶

Current implementation¶

MkDocs is already scaffolded and working locally
a local docs preview is available on port 8011
the app UI runs on port 8000
the GitHub Pages workflow scaffold exists
the docs remain Markdown-first
the legacy portal is still present during transition

Target state¶

MkDocs becomes the primary documentation surface
GitHub Pages becomes the shared hosted docs entry point
repository URLs in documentation/mkdocs.yml are updated to real values
optional richer versioning can be added later if release needs justify it

14. Best Next Step¶

The next clean step after this guide is:

connect the repository to GitHub Pages with real repository metadata

That will complete the transition from a strong local docs platform to a shareable hosted documentation site.