Vishesh 'ironeagle' Bangotra
22fceef020
# Merge Request: Flatten MkDocs Structure + `--module-is-source` Support ## Summary This MR introduces structural improvements to the MkDocs generation pipeline to: 1. Ensure a root `docs/index.md` always exists 2. Flatten documentation structure (remove `docs/<module>/` nesting by default) 3. Add support for `--module-is-source` to treat the module as the documentation root 4. Align navigation (`docforge.nav.yml`) with the new flat layout 5. Regenerate MCP artifacts to reflect updated signatures and docstrings This resolves static hosting issues (e.g., Nginx 403 due to missing `site/index.html`) and makes each generated MkDocs site deployable as a standalone static website. --- ## Motivation Previously, documentation was generated under: ``` docs/<module>/... ``` Which resulted in: ``` site/<module>/index.html ``` When deployed at `/libs/<project>/`, this caused: * Missing `site/index.html` * Nginx returning 403 for root access * Inconsistent static hosting behavior This MR corrects the architecture so each MkDocs build is a valid static site with a root entry point. --- ## Key Changes ### 1️⃣ Flattened Docs Structure **Before** ``` docs/docforge/index.md ``` **After** ``` docs/index.md ``` All documentation paths were updated accordingly: * `docs/docforge/cli/...` → `docs/cli/...` * `docs/docforge/models/...` → `docs/models/...` * `docs/docforge/renderers/...` → `docs/renderers/...` Navigation updated to match the flat layout. --- ### 2️⃣ Root Index Enforcement `MkDocsRenderer` now guarantees: * `docs/index.md` is always created * Parent `index.md` files are auto-generated if missing * Parent indexes link to child modules (idempotent behavior) This ensures: ``` site/index.html ``` Always exists after `mkdocs build`. --- ### 3️⃣ New CLI Flag: `--module-is-source` Added option: ``` --module-is-source ``` Behavior: * Treats the provided module as the documentation root * Removes the top-level module folder from generated paths * Prevents redundant nesting when the module corresponds to the source root Updated components: * `cli.commands.build` * `mkdocs_utils.generate_sources` * `MkDocsRenderer.generate_sources` * Stub files (`.pyi`) * MCP JSON artifacts --- ### 4️⃣ Navigation Spec Update `docforge.nav.yml` updated: **Before** ```yaml home: docforge/index.md ``` **After** ```yaml home: index.md ``` All group paths adjusted to remove `docforge/` prefix. --- ### 5️⃣ MkDocs Config Update `mkdocs.yml` updated to: * Move `site_name` below theme/plugins * Use flat navigation paths * Point Home to `index.md` --- ### 6️⃣ MCP Artifact Regeneration Updated: * Function signatures (new parameter) * Docstrings (reflect `module_is_source`) * Renderer metadata * Line numbers Ensures MCP output matches updated API. --- ## Architectural Outcome Each project now produces a **valid standalone static site**: ``` site/ index.html assets/ search/ ``` Safe for deployment under: ``` /libs/<project>/ ``` No Nginx rewrites required. No directory-index issues. No nested-site ambiguity. --- ## Backward Compatibility * Existing CLI usage remains valid * `--module-is-source` is optional * Navigation spec format unchanged (only paths adjusted) --- ## Deployment Impact After merge: * Each library can be deployed independently * Sites can be merged under a shared root without internal conflicts * Static hosting is predictable and production-safe --- ## Testing * Verified MkDocs build produces `site/index.html` * Verified navigation renders correctly * Verified parent index generation is idempotent * Regenerated MCP docs and validated schema consistency --- ## Result The documentation compiler now: * Produces structurally correct static sites * Supports flat and source-root modes * Eliminates 403 root issues * Scales cleanly across multiple repositories This aligns doc-forge with proper static-site architectural invariants. Reviewed-on: #4 Co-authored-by: Vishesh 'ironeagle' Bangotra <aetoskia@gmail.com> Co-committed-by: Vishesh 'ironeagle' Bangotra <aetoskia@gmail.com>
4 lines
39 B
Markdown
4 lines
39 B
Markdown
# Project
|
|
|
|
::: docforge.models.project
|