aetos/doc-forge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Flatten MkDocs Structure + --module-is-source Support #4

Merged
aetos merged 5 commits from fix-missing-index into main 2026-02-21 16:16:37 +00:00
Conversation 0 Commits 5 Files Changed 38 +306 -218
aetos commented 2026-02-21 15:37:47 +00:00
Owner
Copy Link

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

home: docforge/index.md

After

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.

# 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.
aetos added 5 commits 2026-02-21 15:37:48 +00:00
added root index.md c8f32bf4b9
updated mkdocs configs 8829e16af0
refresh docs and mcp a2ebd7d19b
module is source flag to ensure for single source modules it's not treated as a module but root 5149034d19
renamed pytest to pytests ae3b389a3b
aetos merged commit 22fceef020 into main 2026-02-21 16:16:37 +00:00
aetos deleted branch fix-missing-index 2026-02-21 16:16:37 +00:00
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
aetos
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: aetos/doc-forge#4
No description provided.
Delete Branch "fix-missing-index"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?