Flatten MkDocs Structure + --module-is-source Support (#4)
# 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>
This commit is contained in:
@@ -169,7 +169,7 @@
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.commands.mkdocs_utils.MkDocsRenderer.generate_sources",
|
||||
"signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources')>",
|
||||
"docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project: The project models to render.\n out_dir: Target directory for documentation files."
|
||||
"docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project: The project models to render.\n out_dir: Target directory for documentation files.\n module_is_source: Module is the source folder and to be treated as the root folder."
|
||||
}
|
||||
}
|
||||
},
|
||||
@@ -208,7 +208,7 @@
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.commands.mkdocs_utils.generate_sources",
|
||||
"signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.cli.mkdocs_utils.generate_sources')>",
|
||||
"docstring": "Generate Markdown source files for the specified module.\n\nArgs:\n module: The dotted path of the primary module to document.\n project_name: Optional override for the project name.\n docs_dir: Directory where the generated Markdown files will be written."
|
||||
"docstring": "Generate Markdown source files for the specified module.\n\nArgs:\n module: The dotted path of the primary module to document.\n project_name: Optional override for the project name.\n docs_dir: Directory where the generated Markdown files will be written.\n module_is_source: Module is the source folder and to be treated as the root folder."
|
||||
},
|
||||
"generate_config": {
|
||||
"name": "generate_config",
|
||||
@@ -349,7 +349,7 @@
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.commands.mcp_utils.serve",
|
||||
"signature": "<bound method Alias.signature of Alias('serve', 'docforge.cli.mcp_utils.serve')>",
|
||||
"docstring": "Serve MCP documentation from a pre-built bundle.\n\nArgs:\n mcp_root: Path to the directory containing index.json, nav.json, and modules/."
|
||||
"docstring": "Serve MCP documentation from a pre-built bundle.\n\nArgs:\n module: The dotted path of the primary module to serve.\n mcp_root: Path to the directory containing index.json, nav.json, and modules/."
|
||||
}
|
||||
}
|
||||
},
|
||||
@@ -364,22 +364,22 @@
|
||||
"name": "build",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.commands.build",
|
||||
"signature": "<bound method Function.signature of Function('build', 18, 89)>",
|
||||
"docstring": "Build documentation (MkDocs site or MCP resources).\n\nThis command orchestrates the full build process:\n1. Introspects the code (Griffe)\n2. Renders sources (MkDocs Markdown or MCP JSON)\n3. (MkDocs only) Generates config and runs the final site build.\n\nArgs:\n mcp: Use the MCP documentation builder.\n mkdocs: Use the MkDocs documentation builder.\n module: The dotted path of the module to document.\n project_name: Optional override for the project name.\n site_name: (MkDocs) The site display name. Defaults to module name.\n docs_dir: (MkDocs) Target directory for Markdown sources.\n nav_file: (MkDocs) Path to the docforge.nav.yml specification.\n template: (MkDocs) Optional custom mkdocs.yml template.\n mkdocs_yml: (MkDocs) Target path for the generated mkdocs.yml.\n out_dir: (MCP) Target directory for MCP JSON resources."
|
||||
"signature": "<bound method Function.signature of Function('build', 18, 97)>",
|
||||
"docstring": "Build documentation (MkDocs site or MCP resources).\n\nThis command orchestrates the full build process:\n1. Introspects the code (Griffe)\n2. Renders sources (MkDocs Markdown or MCP JSON)\n3. (MkDocs only) Generates config and runs the final site build.\n\nArgs:\n mcp: Use the MCP documentation builder.\n mkdocs: Use the MkDocs documentation builder.\n module_is_source: Module is the source folder and to be treated as the root folder.\n module: The dotted path of the module to the document.\n project_name: Optional override for the project name.\n site_name: (MkDocs) The site display name. Defaults to module name.\n docs_dir: (MkDocs) Target directory for Markdown sources.\n nav_file: (MkDocs) Path to the docforge.nav.yml specification.\n template: (MkDocs) Optional custom mkdocs.yml template.\n mkdocs_yml: (MkDocs) Target path for the generated mkdocs.yml.\n out_dir: (MCP) Target directory for MCP JSON resources."
|
||||
},
|
||||
"serve": {
|
||||
"name": "serve",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.commands.serve",
|
||||
"signature": "<bound method Function.signature of Function('serve', 92, 120)>",
|
||||
"docstring": "Serve documentation (MkDocs or MCP).\n\nArgs:\n mcp: Serve MCP resources via an MCP server.\n mkdocs: Serve the MkDocs site using the built-in development server.\n mkdocs_yml: (MkDocs) Path to the mkdocs.yml configuration.\n out_dir: (MCP) Path to the mcp_docs/ directory."
|
||||
"signature": "<bound method Function.signature of Function('serve', 100, 133)>",
|
||||
"docstring": "Serve documentation (MkDocs or MCP).\n\nArgs:\n mcp: Serve MCP resources via an MCP server.\n mkdocs: Serve the MkDocs site using the built-in development server.\n module: The dotted path of the module to serve.\n mkdocs_yml: (MkDocs) Path to the mkdocs.yml configuration.\n out_dir: (MCP) Path to the mcp_docs/ directory."
|
||||
},
|
||||
"tree": {
|
||||
"name": "tree",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.commands.tree",
|
||||
"signature": "<bound method Function.signature of Function('tree', 123, 153)>",
|
||||
"docstring": "Visualize the project structure in the terminal.\n\nArgs:\n modules: List of module import paths to recursively introspect.\n project_name: Optional override for the project name shown at the root."
|
||||
"signature": "<bound method Function.signature of Function('tree', 136, 165)>",
|
||||
"docstring": "Visualize the project structure in the terminal.\n\nArgs:\n module: The module import path to recursively introspect.\n project_name: Optional override for the project name shown at the root."
|
||||
},
|
||||
"Group": {
|
||||
"name": "Group",
|
||||
@@ -512,8 +512,8 @@
|
||||
"name": "serve",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.mcp_utils.serve",
|
||||
"signature": "<bound method Function.signature of Function('serve', 23, 47)>",
|
||||
"docstring": "Serve MCP documentation from a pre-built bundle.\n\nArgs:\n mcp_root: Path to the directory containing index.json, nav.json, and modules/."
|
||||
"signature": "<bound method Function.signature of Function('serve', 23, 48)>",
|
||||
"docstring": "Serve MCP documentation from a pre-built bundle.\n\nArgs:\n module: The dotted path of the primary module to serve.\n mcp_root: Path to the directory containing index.json, nav.json, and modules/."
|
||||
}
|
||||
}
|
||||
},
|
||||
@@ -601,7 +601,7 @@
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.mkdocs_utils.MkDocsRenderer.generate_sources",
|
||||
"signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources')>",
|
||||
"docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project: The project models to render.\n out_dir: Target directory for documentation files."
|
||||
"docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project: The project models to render.\n out_dir: Target directory for documentation files.\n module_is_source: Module is the source folder and to be treated as the root folder."
|
||||
}
|
||||
}
|
||||
},
|
||||
@@ -639,28 +639,28 @@
|
||||
"name": "generate_sources",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.mkdocs_utils.generate_sources",
|
||||
"signature": "<bound method Function.signature of Function('generate_sources', 9, 23)>",
|
||||
"docstring": "Generate Markdown source files for the specified module.\n\nArgs:\n module: The dotted path of the primary module to document.\n project_name: Optional override for the project name.\n docs_dir: Directory where the generated Markdown files will be written."
|
||||
"signature": "<bound method Function.signature of Function('generate_sources', 9, 33)>",
|
||||
"docstring": "Generate Markdown source files for the specified module.\n\nArgs:\n module: The dotted path of the primary module to document.\n project_name: Optional override for the project name.\n docs_dir: Directory where the generated Markdown files will be written.\n module_is_source: Module is the source folder and to be treated as the root folder."
|
||||
},
|
||||
"generate_config": {
|
||||
"name": "generate_config",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.mkdocs_utils.generate_config",
|
||||
"signature": "<bound method Function.signature of Function('generate_config', 25, 59)>",
|
||||
"signature": "<bound method Function.signature of Function('generate_config', 35, 69)>",
|
||||
"docstring": "Generate an mkdocs.yml configuration file.\n\nArgs:\n docs_dir: Path to the directory containing documentation Markdown files.\n nav_file: Path to the docforge.nav.yml specification.\n template: Optional path to an mkdocs.yml template (overrides built-in).\n out: Path where the final mkdocs.yml will be written.\n site_name: The display name for the documentation site."
|
||||
},
|
||||
"build": {
|
||||
"name": "build",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.mkdocs_utils.build",
|
||||
"signature": "<bound method Function.signature of Function('build', 61, 74)>",
|
||||
"signature": "<bound method Function.signature of Function('build', 71, 84)>",
|
||||
"docstring": "Build the documentation site using MkDocs.\n\nArgs:\n mkdocs_yml: Path to the mkdocs.yml configuration file."
|
||||
},
|
||||
"serve": {
|
||||
"name": "serve",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.mkdocs_utils.serve",
|
||||
"signature": "<bound method Function.signature of Function('serve', 76, 87)>",
|
||||
"signature": "<bound method Function.signature of Function('serve', 86, 97)>",
|
||||
"docstring": "Serve the documentation site with live-reload using MkDocs.\n\nArgs:\n mkdocs_yml: Path to the mkdocs.yml configuration file."
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user