Skip to content

Build & Serve the Docs

This guide shows how to build, serve, and publish the SmrtHub documentation using the pinned toolchain and provided scripts.

Prerequisites

  • Python 3.11 (3.10+ is fine)
  • PowerShell (pwsh) available in PATH
  • No global installs required: the build script will create/use a local venv and install from MKDocs/docs-requirements.txt.

Everyday workflow

  • Build & serve locally (auto-open browser):
  • VS Code Task: “📖 Build & Serve MKDocs”

  • Or run:

    pwsh -NoProfile -ExecutionPolicy Bypass -File "Tools/MKDocs-Creation/BuildMkDocs.ps1" -Serve -Open

  • One-time clean + install pinned dependencies + build:

pwsh -NoProfile -ExecutionPolicy Bypass -File "Tools/MKDocs-Creation/BuildMkDocs.ps1" -Clean
  • Regenerate component docs from per-component READMEs (whenever SmrtApps/**/README*.md changes):
pwsh -NoProfile -ExecutionPolicy Bypass -File "Tools/Documentation Building/GenerateComponentDocs.ps1"
  • Optional: enable API docs with mkdocstrings (Python only) during local dev:
$env:ENABLE_MKDOCSTRINGS = "true"
pwsh -NoProfile -ExecutionPolicy Bypass -File "Tools/MKDocs-Creation/BuildMkDocs.ps1" -Serve

Documentation pipeline at a glance

flowchart LR
    subgraph Sources
        A[Per-component README.md<br/>SmrtApps/**]
        B[C# XML doc comments<br/>SmrtApps/src builds]
        C[Python docstrings<br/>python_core package]
        D[Hand-written Markdown & assets<br/>MKDocs/docs/**]
    end

    A -->|GenerateComponentDocs.ps1| E[docs/components/auto/*.md]
    B -->|generate_api_docs.py| F[docs/reference/api/dotnet/**/*.md]
    C -->|mkdocstrings plugin|
    D --> H
    E --> H
    F --> H

    H[mkdocs build / serve]
    H --> J[site/ static output or live preview]
  • Tools/Documentation Building/GenerateComponentDocs.ps1 mirrors component READMEs into docs/components/auto/.
  • Tools/Documentation Building/generate_api_docs.py compiles .NET projects, converts XML doc comments, and refreshes the .NET Runtime APIs section.
  • mkdocstrings imports the python_core package at render time, so Python API pages populate live when BuildMkDocs.ps1 runs.

Source-of-truth matrix

Content type Author here How it lands in MKDocs
Component responsibilities, config paths, troubleshooting SmrtApps/**/README*.md (one README per directory by policy) GenerateComponentDocs.ps1 copies to docs/components/auto/** and the nav markers expose them under Components → Runtime Apps / Services / Libraries / Python
.NET API signatures + XML comments Public/internal APIs in SmrtApps/src/** generate_api_docs.py builds the projects, reads the XML doc output, and writes Markdown underneath docs/reference/api/dotnet/** (never hand-edit those files)
Python APIs + docstrings SmrtApps/PythonApp/python_core/** docstrings mkdocstrings renders the modules declared in Tools/Documentation Building/api-docs-config.json during mkdocs build; rerun BuildMkDocs.ps1 after editing docstrings
Governance / policy READMEs README.Files/*.md Copy the canonical README into docs/policies/ (keep filenames identical) and reference it from mkdocs.yml. A change in README.Files must be mirrored in MKDocs the same day
Narrative / how-to articles MKDocs/docs/** Write directly in the relevant folder (operations, reference, contributing, etc.). These are the only Markdown files you edit manually inside MKDocs/docs

When in doubt, update the canonical source first (e.g., component README, XML comments, or README.Files). The automation pulls from those locations; manual edits inside docs/components/auto or docs/reference/api/dotnet will be overwritten the next time the generators run.

Authoring conventions

  • Stubs: prefer plain text + an admonition over placeholder links. Example:
??? note "Coming soon"
    This section is intentionally stubbed for now.

The build is configured to ignore warnings from stub links, but keeping stubs as text avoids confusion for readers.

  • Components: don’t hand-edit the Components list in mkdocs.yml. The generator writes the block between BEGIN/END AUTO-COMPONENTS markers.

  • Assets & theming: Cal Sans and brand tokens are already wired in docs/stylesheets/extra.css. Follow the Asset Policy when changing logos or UI tokens.

Branching & publishing

  • Do docs changes on a small feature branch off main (e.g., docs/tweak-nav) and open a PR to main.
  • Private-friendly CI: the workflow always builds and uploads the static site as an artifact you can download from the run.
  • GitHub Pages publishing is intentionally disabled. Publish privately using the script below.

Private publishing (no GitHub Pages)

  • Create a static site zip:
pwsh -NoProfile -ExecutionPolicy Bypass -File "Tools/Documentation Building/PublishDocs.ps1" -Zip
  • Deploy to a local/remote folder (IIS, shared web root):
pwsh -NoProfile -ExecutionPolicy Bypass -File "Tools/Documentation Building/PublishDocs.ps1" -TargetPath "C:\inetpub\wwwroot\smrthub-docs" -CleanTarget
  • CI artifact: every push builds the site and uploads an artifact named mkdocs-site for download from the Actions run.

Troubleshooting

  • If the server doesn’t auto-reload, stop and re-run -Serve.
  • If dependencies drift, run -Clean to recreate the environment from pinned versions.
  • On CI failures, check that MKDocs/docs-requirements.txt resolved and that mkdocs build succeeds locally.
  • Use the artifact or PublishDocs.ps1 instead of any public publishing mechanism.