Vishesh 'ironeagle' Bangotra
22fceef020
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>
2026-02-21 16:16:36 +00:00
..
2026-02-21 16:16:36 +00:00
2026-02-21 16:16:36 +00:00
2026-02-21 16:16:36 +00:00
2026-02-21 16:16:36 +00:00
2026-02-21 16:16:36 +00:00
2026-02-21 16:16:36 +00:00
2026-02-21 16:16:36 +00:00