John Lancaster
151 lines
3.8 KiB
Markdown
151 lines
3.8 KiB
Markdown
# Static Docs Hosting Pattern
|
|
|
|
## Purpose
|
|
|
|
This document describes the completed layout and runtime pattern used to host a pre-built static documentation site from the same FastAPI app process that runs the FastMCP server.
|
|
|
|
This design intentionally avoids runtime docs rendering and avoids a separate docs hosting service.
|
|
|
|
## Completed-State Layout
|
|
|
|
```text
|
|
project-root/
|
|
|
|
|
|- pyproject.toml
|
|
|- uv.lock
|
|
|- zensical.toml
|
|
|
|
|
|- docs/
|
|
| |- index.md
|
|
| |- architecture.md
|
|
| |- mcp_layout.md
|
|
| |- generated/
|
|
| |- patterns/
|
|
| |- index.md
|
|
| |- pytest-scaffolding.md
|
|
| |- python-logging-dictconfig.md
|
|
| |- fastapi-uv-docker.md
|
|
|
|
|
|- site/
|
|
| |- ... static files built by zensical ...
|
|
|
|
|
|- src/
|
|
|- personal_mcp/
|
|
|- main.py
|
|
|- web/
|
|
| |- app.py
|
|
| |- docs_mount.py
|
|
|- catalog/
|
|
| |- server.py
|
|
|- skills/
|
|
|- pytest_scaffolding/
|
|
|- python_logging_dictconfig/
|
|
|- fastapi_uv_docker/
|
|
```
|
|
|
|
Notes:
|
|
|
|
1. docs contains authored pages and generated markdown pages.
|
|
2. site contains static build output only.
|
|
3. MCP resources and docs generation share the same content contract.
|
|
|
|
## Runtime Composition
|
|
|
|
The runtime process serves two surfaces:
|
|
|
|
1. MCP protocol surface from FastMCP
|
|
2. Static docs surface from FastAPI static mount
|
|
|
|
```mermaid
|
|
flowchart TD
|
|
A[FastMCP Root Server] --> B[MCP Transport]
|
|
A --> C[FastAPI Application]
|
|
C --> D[Static Mount /docs]
|
|
D --> E[Zensical site output directory]
|
|
```
|
|
|
|
## Build and Publish Flow
|
|
|
|
The docs flow is pre-build only.
|
|
|
|
1. Read module resources and catalog metadata.
|
|
2. Generate docs markdown pages into docs/generated.
|
|
3. Build static site with Zensical into site.
|
|
4. Start app and serve site directory as static files.
|
|
|
|
No runtime markdown conversion is required.
|
|
|
|
## Content Merge Pattern
|
|
|
|
The published docs site always contains both:
|
|
|
|
1. Project-authored docs pages
|
|
2. Resource-derived pattern pages
|
|
|
|
This ensures the public docs reflect both architectural guidance and live pattern knowledge.
|
|
|
|
## Resource-to-Docs Mapping
|
|
|
|
Pattern resources map directly to docs sections.
|
|
|
|
Example mapping model:
|
|
|
|
1. resource://skills/<id>/overview -> docs/generated/patterns/<id>.md section Overview
|
|
2. resource://skills/<id>/rules -> docs/generated/patterns/<id>.md section Rules
|
|
3. resource://skills/<id>/checklist -> docs/generated/patterns/<id>.md section Checklist
|
|
4. resource://skills/<id>/references -> docs/generated/patterns/<id>.md section References
|
|
|
|
Catalog resources generate index pages and navigation pages.
|
|
|
|
## Why This Pattern
|
|
|
|
### Operational Simplicity
|
|
|
|
One application process serves both protocol and static docs surfaces.
|
|
|
|
### Deterministic Docs
|
|
|
|
Published docs are immutable static assets for a given build.
|
|
|
|
### Documentation Fidelity
|
|
|
|
Resource-derived pages align docs with the exact methodology contracts exposed to agents.
|
|
|
|
### Maintainer Experience
|
|
|
|
Authors continue to work in markdown while resource contracts remain machine-consumable.
|
|
|
|
## FastAPI Static Mount Expectations
|
|
|
|
The FastAPI app is expected to:
|
|
|
|
1. Mount static directory containing Zensical output.
|
|
2. Serve index and asset files from that directory.
|
|
3. Keep docs route stable across releases.
|
|
|
|
Recommended route conventions:
|
|
|
|
1. /docs for static site root
|
|
2. /docs/* for static assets and page routes
|
|
|
|
## Update Lifecycle
|
|
|
|
For each documentation update:
|
|
|
|
1. Edit authored markdown and resource content.
|
|
2. Regenerate docs markdown from resources.
|
|
3. Rebuild static site.
|
|
4. Restart runtime if needed.
|
|
|
|
This keeps docs publication explicit and predictable.
|
|
|
|
## Example Source Material
|
|
|
|
Existing reference docs remain valid content inputs in this pattern:
|
|
|
|
1. ../skills/pytest-scaffolding/references/pytest-docs.md
|
|
2. ../skills/python-logging-dictconfig/references/python-logging-docs.md
|
|
3. ../skills/fastapi-uv-docker/references/fastapi-best-practices.md
|
|
|
|
These are source documents, not deployment artifacts.
|