added hierarchy rules

# 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>

.run/pytests.run.xml

@@ -1,5 +1,5 @@
 <component name="ProjectRunConfigurationManager">
-  <configuration default="false" name="pytest" type="tests" factoryName="py.test">
+  <configuration default="false" name="pytests" type="tests" factoryName="py.test">
     <module name="docforge" />
     <option name="ENV_FILES" value="" />
     <option name="INTERPRETER_OPTIONS" value="" />

ADS.llm.md

@@ -1,327 +0,0 @@
-# doc-forge — Architecture & Design Specification
-
-**doc-forge** is a renderer-agnostic Python documentation compiler. It converts Python source code and docstrings into a structured, semantic documentation model and then emits multiple downstream representations, including:
-
-* Human-facing documentation sites (MkDocs, Sphinx)
-* Machine-facing documentation bundles (MCP JSON)
-* Live documentation APIs (MCP servers)
-
-This document is the **authoritative design and codebase specification** for the library. It is written to be both **LLM-friendly** and **developer-facing**, and should be treated as the canonical reference for implementation decisions.
-
----
-
-## 1. Design Goals
-
-1. **Single Source of Truth**
-   Python source code and docstrings are the only authoritative input.
-
-2. **Renderer Agnosticism**
-   MkDocs, Sphinx, MCP, or future renderers must not influence the core model.
-
-3. **Deterministic Output**
-   Given the same codebase, outputs must be reproducible.
-
-4. **AI-Native Documentation**
-   Documentation must be structured, queryable, and machine-consumable.
-
-5. **Library-First, CLI-Second**
-   All functionality must be accessible as a Python API. The CLI is a thin wrapper.
-
----
-
-## 2. Core Mental Model
-
-### Fundamental Abstraction
-
-> **The atomic unit of documentation is a Python import path**
-
-Examples:
-
-* `mail_intake`
-* `mail_intake.config`
-* `mail_intake.adapters.base`
-
-Files, Markdown, HTML, and JSON are *representations*, not documentation units.
-
----
-
-## 3. High-Level Architecture
-
-```
-Python Source Code
-        ↓
-Introspection Layer (Griffe)
-        ↓
-Documentation Model (doc-forge core)
-        ↓
-Renderer / Exporter Layer
-   ├── MkDocs
-   ├── Sphinx
-   ├── MCP (static JSON)
-   └── MCP Server (live)
-```
-
-Only the **Documentation Model** is shared across all outputs.
-
----
-
-## 4. Package Layout (Proposed)
-
-```
-docforge/
-├── __init__.py
-├── model/
-│   ├── project.py
-│   ├── module.py
-│   ├── object.py
-│   └── nav.py
-├── loader/
-│   └── griffe_loader.py
-├── renderers/
-│   ├── base.py
-│   ├── mkdocs.py
-│   └── sphinx.py
-├── exporters/
-│   └── mcp.py
-├── server/
-│   └── mcp_server.py
-├── cli/
-│   └── main.py
-└── utils/
-```
-
----
-
-## 5. Documentation Model (Core)
-
-The documentation model is renderer-neutral and must not contain any MkDocs-, Sphinx-, or MCP-specific logic.
-
-### 5.1 Project
-
-```python
-class Project:
-    name: str
-    version: str | None
-    modules: dict[str, Module]
-    nav: Navigation
-```
-
----
-
-### 5.2 Module
-
-```python
-class Module:
-    path: str                # import path
-    docstring: str | None
-    members: dict[str, DocObject]
-```
-
----
-
-### 5.3 DocObject
-
-Represents classes, functions, variables, etc.
-
-```python
-class DocObject:
-    name: str
-    kind: str                # class, function, attribute, module
-    path: str
-    signature: str | None
-    docstring: str | None
-    members: dict[str, DocObject]
-```
-
-Private members (`_name`) are excluded by default.
-
----
-
-### 5.4 Navigation
-
-```python
-class Navigation:
-    entries: list[NavEntry]
-
-class NavEntry:
-    title: str
-    module: str
-```
-
-Navigation is derived, not authored.
-
----
-
-## 6. Introspection Layer
-
-### 6.1 Griffe Loader
-
-Griffe is the **only supported introspection backend**.
-
-Responsibilities:
-
-* Load modules by import path
-* Resolve docstrings, signatures, and members
-* Tolerate alias resolution failures
-
-Output: fully populated `Project` and `Module` objects.
-
----
-
-## 7. Renderer Interface
-
-Renderers consume the documentation model and emit renderer-specific source trees.
-
-```python
-class DocRenderer(Protocol):
-    name: str
-
-    def generate_sources(self, project: Project, out_dir: Path) -> None:
-        """Generate renderer-specific source files."""
-
-    def build(self, config: RendererConfig) -> None:
-        """Build final artifacts (HTML, site, etc.)."""
-
-    def serve(self, config: RendererConfig) -> None:
-        """Serve documentation locally (optional)."""
-```
-
----
-
-## 8. MkDocs Renderer
-
-### Source Generation
-
-* Emits `.md` files
-* One file per module
-* Uses `mkdocstrings` directives exclusively
-
-```md
-# Config
-
-::: mail_intake.config
-```
-
-### Build
-
-* Uses `mkdocs.commands.build`
-
-### Serve
-
-* Uses `mkdocs.commands.serve`
-
-MkDocs-specific configuration lives outside the core model.
-
----
-
-## 9. Sphinx Renderer
-
-### Source Generation
-
-* Emits `.rst` files
-* Uses `autodoc` directives
-
-```rst
-mail_intake.config
-==================
-
-.. automodule:: mail_intake.config
-   :members:
-   :undoc-members:
-```
-
-### Build
-
-* Uses `sphinx.application.Sphinx` directly
-
-### Serve
-
-* Optional (static build is sufficient)
-
----
-
-## 10. MCP Exporter (Static)
-
-The MCP exporter bypasses renderers entirely.
-
-### Output Structure
-
-```
-mcp/
-├── index.json
-├── nav.json
-└── modules/
-    └── package.module.json
-```
-
-### Design Principles
-
-* Alias-safe
-* Deterministic
-* Fully self-contained
-* No Markdown, HTML, or templates
-
----
-
-## 11. MCP Server (Live)
-
-The MCP server exposes documentation as queryable resources.
-
-### Resources
-
-* `docs://index`
-* `docs://nav`
-* `docs://module/{module}`
-
-### Characteristics
-
-* Read-only
-* Stateless
-* Backed by MCP JSON bundle
-
----
-
-## 12. CLI Design
-
-The CLI is a thin orchestration layer.
-
-```bash
-doc-forge generate --renderer mkdocs
-doc-forge generate --renderer sphinx
-
-doc-forge build --renderer mkdocs
-doc-forge serve --renderer mkdocs
-
-doc-forge export mcp
-```
-
-Renderer choice never affects the core model.
-
----
-
-## 13. Explicit Non-Goals
-
-* Markdown authoring
-* Theme design
-* Runtime code execution
-* Code formatting or linting
-
----
-
-## 14. Invariants (Must Never Break)
-
-1. Import paths are canonical identifiers
-2. Core model contains no renderer logic
-3. MCP does not depend on MkDocs or Sphinx
-4. Renderers do not introspect Python directly
-5. All outputs trace back to the same model
-
----
-
-## 15. One-Line Definition
-
-> **doc-forge is a documentation compiler that turns Python code into structured knowledge and emits it through multiple human and machine interfaces.**
-
----
-
-*End of specification.*

docforge.nav.yml

@@ -1,26 +1,26 @@
-home: docforge/index.md
+home: index.md
 groups:
   Loaders:
-    - docforge/loaders/index.md
+    - loaders/index.md
-    - docforge/loaders/griffe_loader.md
+    - loaders/griffe_loader.md
   Models:
-    - docforge/models/index.md
+    - models/index.md
-    - docforge/models/module.md
+    - models/module.md
-    - docforge/models/object.md
+    - models/object.md
-    - docforge/models/project.md
+    - models/project.md
   Navigation:
-    - docforge/nav/index.md
+    - nav/index.md
-    - docforge/nav/spec.md
+    - nav/spec.md
-    - docforge/nav/resolver.md
+    - nav/resolver.md
-    - docforge/nav/mkdocs.md
+    - nav/mkdocs.md
   Renderers:
-    - docforge/renderers/index.md
+    - renderers/index.md
-    - docforge/renderers/base.md
+    - renderers/base.md
-    - docforge/renderers/mkdocs_renderer.md
+    - renderers/mkdocs_renderer.md
-    - docforge/renderers/mcp_renderer.md
+    - renderers/mcp_renderer.md
   CLI:
-    - docforge/cli/index.md
+    - cli/index.md
-    - docforge/cli/main.md
+    - cli/main.md
-    - docforge/cli/commands.md
+    - cli/commands.md
-    - docforge/cli/mcp_utils.md
+    - cli/mcp_utils.md
-    - docforge/cli/mkdocs_utils.md
+    - cli/mkdocs_utils.md

docforge/__init__.py

@@ -1,63 +1,270 @@
 """
-# doc-forge
+Renderer-agnostic Python documentation compiler that converts docstrings into
+structured documentation for both humans (MkDocs) and machines (MCP / AI agents).
 
-`doc-forge` is a renderer-agnostic Python documentation compiler designed for
+`doc-forge` statically analyzes your source code, builds a semantic model of
-speed, flexibility, and beautiful output. It decouples the introspection of
+modules and objects, and renders that model into documentation outputs without
-your code from the rendering process, allowing you to generate documentation
+executing your code.
-for various platforms (starting with MkDocs) from a single internal models.
+---
 
-## Available Commands
+# Core Philosophy
 
-- **build**: Build documentation (MkDocs site or MCP resources).
+`doc-forge` follows a compiler architecture:
-- **serve**: Serve documentation (MkDocs or MCP).
-- **tree**: Visualize the introspected project structure.
 
-## Installation
+1. **Front-end (Introspection)**
+   Static analysis of modules, classes, functions, signatures, and docstrings.
 
-Install using `pip` with the optional `mkdocs` dependencies for a complete setup:
+2. **Middle-end (Semantic Model)**
+   Renderer-neutral structured representation of your API.
 
-```bash
+3. **Back-end (Renderers)**
-pip install doc-forge
+
+   * MkDocs → human documentation
+   * MCP JSON → AI-readable documentation
+---
+
+# Docstring Writing Standard
+
+Docstrings are the single source of truth. `doc-forge` does not generate content.
+It compiles and renders what you write.
+
+Documentation follows the Python import hierarchy.
+---
+
+# Package docstring (`package/__init__.py`) — Full user guide
+
+This is the landing page. A developer must be able to install and use the
+package after reading only this docstring.
+
+## Example:
+
+    '''
+    Short description of what this package provides.
+
+    # Installation
+
+    ```bash
+    pip install my-package
+    ```
+
+    # Quick start
+
+    ```python
+    from my_package.foo import Bar
+
+    bar = Bar()
+    result = bar.process("example")
+    ```
+    ---
+
+    # Core concepts
+
+    ## Bar
+    - Primary object exposed by the package.
+
+    ## foo module
+    - Provides core functionality.
+    ---
+
+    # Typical workflow
+
+    1. Import public objects
+    2. Initialize objects
+    3. Call methods
+    ---
+
+    # Public API
+
+    foo.Bar
+    foo.helper_function
+    ---
+    '''
+---
+
+# Submodule docstring (`package/foo/__init__.py`) — Subsystem guide
+
+Explains a specific subsystem.
+
+## Example:
+
+    '''
+    Provides core functionality.
+
+    # Usage
+
+    ```python
+    from my_package.foo import Bar
+
+    bar = Bar()
+    bar.process("example")
+    ```
+    ---
+    '''
+---
+
+# Class docstring — Object contract
+
+Defines responsibility and behavior.
+
+## Example:
+
+```python
+class Bar:
+    '''
+    Performs processing on input data.
+
+    Instances may be reused across multiple calls.
+    ---
+    '''
 ```
 
-## Quick Start
+Include:
 
-1.  **Build Documentation**:
+* Responsibility
-    Introspect your package and generate documentation in one step:
+* Lifecycle expectations
-    ```bash
+* Thread safety (if relevant)
-    # Build MkDocs site
+* Performance characteristics (if relevant)
-    doc-forge build --mkdocs --module my_package --site-name "My Docs"
+---
 
-    # Build MCP resources
+# Function and method docstrings — API specification
-    doc-forge build --mcp --module my_package
-    ```
 
-2.  **Define Navigation**:
+## Example:
-    Create a `docforge.nav.yml` to organize your documentation:
-    ```yaml
-    home: my_package/index.md
-    groups:
-      Core API:
-        - my_package/core/*.md
-      Utilities:
-        - my_package/utils.md
-    ```
 
-3.  **Preview**:
+```python
-    ```bash
+def process(
-    # Serve MkDocs site
+    self,
-    doc-forge serve --mkdocs
+    value1: str,
+    value2: str | None = "default value",
+    value3: str | None = None,
+) -> str:
+    '''
+    Process an input value.
+    ---
 
-    # Serve MCP documentation
+    Parameters
-    doc-forge serve --mcp
+    ----------
-    ```
+    value1 : str
+        required: True
+        value to be processed
+        Example:
+            'string'
 
-## Project Structure
+    value2 : str
+        required: False
+        default: "default value"
+        value to be processed
+        Example:
+            'string'
 
-- `docforge.loaders`: Introspects source code using static analysis (`griffe`).
+    value3 : str
-- `docforge.models`: The internal representation of your project, modules, and objects.
+        required: False
-- `docforge.renderers`: Converters that turn the models into physical files.
+        value to be processed
-- `docforge.nav`: Managers for logical-to-physical path mapping and navigation.
+        Example:
+            'string'
+    ---
+
+    Returns
+    -------
+    processed value : str
+        result after processing value
+    ---
+
+    Behavior
+    --------
+    - behaviour 1
+    - behaviour 2
+    ---
+    '''
+```
+---
+
+# Attribute docstrings (optional)
+
+## Example:
+
+```python
+class Class
+    '''
+    attribute1 : str
+        required: True
+        default: "default value"
+        attribute description
+
+    attribute2 : str
+        required: False
+        attribute description
+
+    attribute2 : str
+        required: False
+        default: "default value"
+        attribute description
+    '''
+
+    attribute1: str = "default value"
+    attribute2: str | None = None
+    attribute3: str | None = "default value"
+```
+---
+
+# Writing Rules
+
+**Heading hierarchy**
+
+Module docstring
+
+- Examples
+- Usage
+- Core concepts
+- Public API
+
+Class docstring
+
+- Attributes
+- Execution contract
+- Lifecycle
+- Thread safety
+- Notes
+
+Method docstring
+
+- Parameters
+- Returns
+- Raises
+- Yields
+- Behavior
+
+**Required**
+
+* Use Markdown headings
+* Use Markdown line separator `---`
+* Line separator should be followed by a blank line
+* Provide real import examples
+* Document all public APIs
+* Keep descriptions precise and factual
+
+**Avoid**
+
+* Plain-text separators like `====`
+* Duplicate external documentation
+* Informal or conversational language
+---
+
+# How doc-forge uses these docstrings
+
+## Build MkDocs site:
+
+```bash
+doc-forge build --mkdocs --module my_package
+```
+
+## Build MCP documentation:
+
+```bash
+doc-forge build --mcp --module my_package
+```
+
+Both outputs are generated directly from docstrings.
+---
 """
 
 from .loaders import GriffeLoader, discover_module_paths

docforge/cli/commands.py

@@ -18,6 +18,7 @@ def cli() -> None:
 @cli.command()
 @click.option("--mcp", is_flag=True, help="Build MCP resources")
 @click.option("--mkdocs", is_flag=True, help="Build MkDocs site")
+@click.option("--module-is-source", is_flag=True, help="Module is source folder and to be treated as root folder")
 @click.option("--module", help="Python module to document")
 @click.option("--project-name", help="Project name override")
 # MkDocs specific
@@ -32,6 +33,7 @@ def cli() -> None:
 def build(
     mcp: bool,
     mkdocs: bool,
+    module_is_source: bool,
     module: Optional[str],
     project_name: Optional[str],
     site_name: Optional[str],
@@ -52,7 +54,8 @@ def build(
     Args:
         mcp: Use the MCP documentation builder.
         mkdocs: Use the MkDocs documentation builder.
-        module: The dotted path of the module to document.
+        module_is_source: Module is the source folder and to be treated as the root folder.
+        module: The dotted path of the module to the document.
         project_name: Optional override for the project name.
         site_name: (MkDocs) The site display name. Defaults to module name.
         docs_dir: (MkDocs) Target directory for Markdown sources.
@@ -71,7 +74,12 @@ def build(
             site_name = module
 
         click.echo(f"Generating MkDocs sources in {docs_dir}...")
-        mkdocs_utils.generate_sources(module, project_name, docs_dir)
+        mkdocs_utils.generate_sources(
+            module,
+            docs_dir,
+            project_name,
+            module_is_source,
+        )
 
         click.echo(f"Generating MkDocs config {mkdocs_yml}...")
         mkdocs_utils.generate_config(docs_dir, nav_file, template, mkdocs_yml, site_name)
@@ -92,11 +100,13 @@ def build(
 @cli.command()
 @click.option("--mcp", is_flag=True, help="Serve MCP documentation")
 @click.option("--mkdocs", is_flag=True, help="Serve MkDocs site")
+@click.option("--module", help="Python module to serve")
 @click.option("--mkdocs-yml", type=click.Path(path_type=Path), default=Path("mkdocs.yml"), help="MkDocs config path")
 @click.option("--out-dir", type=click.Path(path_type=Path), default=Path("mcp_docs"), help="MCP root directory")
 def serve(
     mcp: bool,
     mkdocs: bool,
+    module: Optional[str],
     mkdocs_yml: Path,
     out_dir: Path,
 ) -> None:
@@ -106,6 +116,7 @@ def serve(
     Args:
         mcp: Serve MCP resources via an MCP server.
         mkdocs: Serve the MkDocs site using the built-in development server.
+        module: The dotted path of the module to serve.
         mkdocs_yml: (MkDocs) Path to the mkdocs.yml configuration.
         out_dir: (MCP) Path to the mcp_docs/ directory.
     """
@@ -113,37 +124,38 @@ def serve(
         raise click.UsageError("Cannot specify both --mcp and --mkdocs")
     if not mcp and not mkdocs:
         raise click.UsageError("Must specify either --mcp or --mkdocs")
+    if mcp and not module:
+        raise click.UsageError("--module is required for MCP serve")
 
     if mkdocs:
         mkdocs_utils.serve(mkdocs_yml)
     elif mcp:
-        mcp_utils.serve(out_dir)
+        mcp_utils.serve(module, out_dir)
 
 
 @cli.command()
 @click.option(
-    "--modules",
+    "--module",
-    multiple=True,
     required=True,
-    help="Python module import paths to introspect",
+    help="Python module import path to introspect",
 )
 @click.option(
     "--project-name",
-    help="Project name (defaults to first module)",
+    help="Project name (defaults to specified module)",
 )
 def tree(
-    modules: Sequence[str],
+    module: str,
     project_name: Optional[str],
 ) -> None:
     """
     Visualize the project structure in the terminal.
 
     Args:
-        modules: List of module import paths to recursively introspect.
+        module: The module import path to recursively introspect.
         project_name: Optional override for the project name shown at the root.
     """
     loader = GriffeLoader()
-    project = loader.load_project(list(modules), project_name)
+    project = loader.load_project([module], project_name)
 
     click.echo(project.name)
 

docforge/cli/commands.pyi

@@ -7,6 +7,7 @@ cli: Group
 def build(
     mcp: bool,
     mkdocs: bool,
+    module_is_source: bool,
     module: Optional[str],
     project_name: Optional[str],
     site_name: Optional[str],
@@ -20,12 +21,13 @@ def build(
 def serve(
     mcp: bool,
     mkdocs: bool,
+    module: Optional[str],
     mkdocs_yml: Path,
     out_dir: Path,
 ) -> None: ...
 
 def tree(
-    modules: Sequence[str],
+    module: str,
     project_name: Optional[str],
 ) -> None: ...
 

docforge/cli/mcp_utils.py

@@ -20,11 +20,12 @@ def generate_resources(module: str, project_name: str | None, out_dir: Path) ->
     renderer = MCPRenderer()
     renderer.generate_sources(project, out_dir)
 
-def serve(mcp_root: Path) -> None:
+def serve(module: str, mcp_root: Path) -> None:
     """
     Serve MCP documentation from a pre-built bundle.
 
     Args:
+        module: The dotted path of the primary module to serve.
         mcp_root: Path to the directory containing index.json, nav.json, and modules/.
     """
     if not mcp_root.exists():
@@ -42,6 +43,6 @@ def serve(mcp_root: Path) -> None:
 
     server = MCPServer(
         mcp_root=mcp_root,
-        name="doc-forge-mcp",
+        name=f"{module}-mcp",
     )
     server.run()

docforge/cli/mcp_utils.pyi

@@ -1,4 +1,4 @@
 from pathlib import Path
 
 def generate_resources(module: str, project_name: str | None, out_dir: Path) -> None: ...
-def serve(mcp_root: Path) -> None: ...
+def serve(module: str, mcp_root: Path) -> None: ...

docforge/cli/mkdocs_utils.py

@@ -6,7 +6,12 @@ from docforge.loaders import GriffeLoader, discover_module_paths
 from docforge.renderers import MkDocsRenderer
 from docforge.nav import load_nav_spec, resolve_nav, MkDocsNavEmitter
 
-def generate_sources(module: str, project_name: str | None, docs_dir: Path) -> None:
+def generate_sources(
+    module: str,
+    docs_dir: Path,
+    project_name: str | None = None,
+    module_is_source: bool | None = None,
+) -> None:
     """
     Generate Markdown source files for the specified module.
 
@@ -14,13 +19,18 @@ def generate_sources(module: str, project_name: str | None, docs_dir: Path) -> N
         module: The dotted path of the primary module to document.
         project_name: Optional override for the project name.
         docs_dir: Directory where the generated Markdown files will be written.
+        module_is_source: Module is the source folder and to be treated as the root folder.
     """
     loader = GriffeLoader()
     discovered_paths = discover_module_paths(module)
     project = loader.load_project(discovered_paths, project_name)
 
     renderer = MkDocsRenderer()
-    renderer.generate_sources(project, docs_dir)
+    renderer.generate_sources(
+        project,
+        docs_dir,
+        module_is_source,
+    )
 
 def generate_config(docs_dir: Path, nav_file: Path, template: Path | None, out: Path, site_name: str) -> None:
     """

docforge/cli/mkdocs_utils.pyi

@@ -1,6 +1,11 @@
 from pathlib import Path
 
-def generate_sources(module: str, project_name: str | None, docs_dir: Path) -> None: ...
+def generate_sources(
+    module: str,
+    docs_dir: Path,
+    project_name: str | None = None,
+    module_is_source: bool | None = None,
+) -> None: ...
 def generate_config(docs_dir: Path, nav_file: Path, template: Path | None, out: Path, site_name: str) -> None: ...
 def build(mkdocs_yml: Path) -> None: ...
 def serve(mkdocs_yml: Path) -> None: ...

docforge/renderers/mkdocs_renderer.py

@@ -1,11 +1,16 @@
 """
-This module implements the MkDocsRenderer, which generates Markdown source files
+MkDocsRenderer
-compatible with the MkDocs 'material' theme and 'mkdocstrings' extension.
+
+Generates Markdown source files compatible with MkDocs Material
+and mkdocstrings, ensuring:
+
+- Root index.md always exists
+- Parent package indexes are created automatically
+- Child modules are linked in parent index files
 """
 
 from pathlib import Path
-
+from docforge.models import Project, Module
-from docforge.models import Project
 
 
 class MkDocsRenderer:
@@ -16,7 +21,15 @@ class MkDocsRenderer:
 
     name = "mkdocs"
 
-    def generate_sources(self, project: Project, out_dir: Path) -> None:
+    # -------------------------
+    # Public API
+    # -------------------------
+    def generate_sources(
+        self,
+        project: Project,
+        out_dir: Path,
+        module_is_source: bool | None = None,
+    ) -> None:
         """
         Produce a set of Markdown files in the output directory based on the
         provided Project models.
@@ -24,7 +37,11 @@ class MkDocsRenderer:
         Args:
             project: The project models to render.
             out_dir: Target directory for documentation files.
+            module_is_source: Module is the source folder and to be treated as the root folder.
         """
+        out_dir.mkdir(parents=True, exist_ok=True)
+        self._ensure_root_index(project, out_dir)
+
         modules = list(project.get_all_modules())
         paths = {m.path for m in modules}
 
@@ -35,12 +52,23 @@ class MkDocsRenderer:
         }
 
         for module in modules:
-            self._write_module(module, packages, out_dir)
+            self._write_module(
+                module,
+                packages,
+                out_dir,
+                module_is_source,
+            )
 
     # -------------------------
     # Internal helpers
     # -------------------------
-    def _write_module(self, module, packages: set[str], out_dir: Path) -> None:
+    def _write_module(
+        self,
+        module: Module,
+        packages: set[str],
+        out_dir: Path,
+        module_is_source: bool | None = None,
+    ) -> None:
         """
         Write a single module's documentation file. Packages are written as
         'index.md' inside their respective directories.
@@ -49,31 +77,37 @@ class MkDocsRenderer:
             module: The module to write.
             packages: A set of module paths that are identified as packages.
             out_dir: The base output directory.
+            module_is_source: Module is the source folder and to be treated as the root folder.
         """
         parts = module.path.split(".")
 
+        if module_is_source:
+            module_name, parts = parts[0], parts[1:]
+        else:
+            module_name, parts = parts[0], parts
+
         if module.path in packages:
-            # package → index.md
+            # Package → directory/index.md
             dir_path = out_dir.joinpath(*parts)
             dir_path.mkdir(parents=True, exist_ok=True)
-
             md_path = dir_path / "index.md"
-            title = parts[-1].replace("_", " ").title()
+            link_target = f"{parts[-1]}/" if parts else None
         else:
-            # leaf module → <name>.md
+            # Leaf module → parent_dir/<name>.md
             dir_path = out_dir.joinpath(*parts[:-1])
             dir_path.mkdir(parents=True, exist_ok=True)
-
             md_path = dir_path / f"{parts[-1]}.md"
-            title = parts[-1].replace("_", " ").title()
+            link_target = f"{parts[-1]}.md" if parts else None
 
+        title = parts[-1].replace("_", " ").title() if parts else module_name
         content = self._render_markdown(title, module.path)
 
-        if md_path.exists() and md_path.read_text(encoding="utf-8") == content:
+        if not md_path.exists() or md_path.read_text(encoding="utf-8") != content:
-            return
-
             md_path.write_text(content, encoding="utf-8")
 
+        if not module_is_source:
+            self._ensure_parent_index(parts, out_dir, link_target, title)
+
     def _render_markdown(self, title: str, module_path: str) -> str:
         """
         Generate the Markdown content for a module file.
@@ -89,3 +123,46 @@ class MkDocsRenderer:
             f"# {title}\n\n"
             f"::: {module_path}\n"
         )
+
+    def _ensure_root_index(
+        self,
+        project: Project,
+        out_dir: Path
+    ) -> None:
+        root_index = out_dir / "index.md"
+
+        if not root_index.exists():
+            root_index.write_text(
+                f"# {project.name}\n\n"
+                "## Modules\n\n",
+                encoding="utf-8",
+            )
+
+    def _ensure_parent_index(
+        self,
+        parts: list[str],
+        out_dir: Path,
+        link_target: str,
+        title: str,
+    ) -> None:
+        if len(parts) == 1:
+            parent_index = out_dir / "index.md"
+            link = f"- [{title}]({link_target})\n"
+        else:
+            parent_dir = out_dir.joinpath(*parts[:-1])
+            parent_dir.mkdir(parents=True, exist_ok=True)
+            parent_index = parent_dir / "index.md"
+
+            link = f"- [{title}]({link_target})\n"
+
+            if not parent_index.exists():
+                parent_title = parts[-2].replace("_", " ").title()
+                parent_index.write_text(
+                    f"# {parent_title}\n\n",
+                    encoding="utf-8",
+                )
+
+        content = parent_index.read_text(encoding="utf-8")
+
+        if link not in content:
+            parent_index.write_text(content + link, encoding="utf-8")

docforge/renderers/mkdocs_renderer.pyi

@@ -1,17 +1,27 @@
 from pathlib import Path
-from typing import Set
-
 from docforge.models import Project, Module
 
 
 class MkDocsRenderer:
     name: str
 
-    def generate_sources(self, project: Project, out_dir: Path) -> None: ...
+    def generate_sources(
+        self,
+        project: Project,
+        out_dir: Path,
+        module_is_source: bool | None = None,
+    ) -> None: ...
+
     def _write_module(
         self,
         module: Module,
-        packages: Set[str],
+        packages: set[str],
         out_dir: Path,
+        module_is_source: bool | None = None,
     ) -> None: ...
+
     def _render_markdown(self, title: str, module_path: str) -> str: ...
+
+    def _ensure_root_index(self, project, out_dir) -> None: ...
+
+    def _ensure_parent_index(self, parts, out_dir, link_target, title) -> None: ...

docforge/templates/mkdocs.sample.yml

@@ -31,3 +31,8 @@ plugins:
             annotations_path: brief
             show_root_heading: true
             group_by_category: true
+
+markdown_extensions:
+  - pymdownx.superfences
+  - pymdownx.tabbed:
+      alternate_style: true

docs/index.md

@@ -1,3 +1,3 @@
-# Docforge
+# docforge
 
 ::: docforge

mcp_docs/modules/docforge.cli.commands.json

@@ -139,7 +139,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."
               }
             }
           },
@@ -178,7 +178,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",
@@ -319,7 +319,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/."
           }
         }
       },
@@ -334,22 +334,22 @@
         "name": "build",
         "kind": "function",
         "path": "docforge.cli.commands.build",
-        "signature": "<bound method Function.signature of Function('build', 18, 89)>",
+        "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: 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."
+        "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)>",
+        "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    mkdocs_yml: (MkDocs) Path to the mkdocs.yml configuration.\n    out_dir: (MCP) Path to the mcp_docs/ directory."
+        "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)>",
+        "signature": "<bound method Function.signature of Function('tree', 136, 165)>",
-        "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."
+        "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",

mcp_docs/modules/docforge.cli.json

@@ -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)>",
+            "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: 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."
+            "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)>",
+            "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    mkdocs_yml: (MkDocs) Path to the mkdocs.yml configuration.\n    out_dir: (MCP) Path to the mcp_docs/ directory."
+            "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)>",
+            "signature": "<bound method Function.signature of Function('tree', 136, 165)>",
-            "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."
+            "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)>",
+            "signature": "<bound method Function.signature of Function('serve', 23, 48)>",
-            "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/."
           }
         }
       },
@@ -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)>",
+            "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."
+            "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."
           }
         }

mcp_docs/modules/docforge.cli.mcp_utils.json

@@ -112,8 +112,8 @@
         "name": "serve",
         "kind": "function",
         "path": "docforge.cli.mcp_utils.serve",
-        "signature": "<bound method Function.signature of Function('serve', 23, 47)>",
+        "signature": "<bound method Function.signature of Function('serve', 23, 48)>",
-        "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/."
       }
     }
   }

mcp_docs/modules/docforge.cli.mkdocs_utils.json

@@ -81,7 +81,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."
           }
         }
       },
@@ -119,28 +119,28 @@
         "name": "generate_sources",
         "kind": "function",
         "path": "docforge.cli.mkdocs_utils.generate_sources",
-        "signature": "<bound method Function.signature of Function('generate_sources', 9, 23)>",
+        "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."
+        "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."
       }
     }

mcp_docs/modules/docforge.json

@@ -2,7 +2,7 @@
   "module": "docforge",
   "content": {
     "path": "docforge",
-    "docstring": "# doc-forge\n\n`doc-forge` is a renderer-agnostic Python documentation compiler designed for\nspeed, flexibility, and beautiful output. It decouples the introspection of\nyour code from the rendering process, allowing you to generate documentation\nfor various platforms (starting with MkDocs) from a single internal models.\n\n## Available Commands\n\n- **build**: Build documentation (MkDocs site or MCP resources).\n- **serve**: Serve documentation (MkDocs or MCP).\n- **tree**: Visualize the introspected project structure.\n\n## Installation\n\nInstall using `pip` with the optional `mkdocs` dependencies for a complete setup:\n\n```bash\npip install doc-forge\n```\n\n## Quick Start\n\n1.  **Build Documentation**:\n    Introspect your package and generate documentation in one step:\n    ```bash\n    # Build MkDocs site\n    doc-forge build --mkdocs --module my_package --site-name \"My Docs\"\n\n    # Build MCP resources\n    doc-forge build --mcp --module my_package\n    ```\n\n2.  **Define Navigation**:\n    Create a `docforge.nav.yml` to organize your documentation:\n    ```yaml\n    home: my_package/index.md\n    groups:\n      Core API:\n        - my_package/core/*.md\n      Utilities:\n        - my_package/utils.md\n    ```\n\n3.  **Preview**:\n    ```bash\n    # Serve MkDocs site\n    doc-forge serve --mkdocs\n\n    # Serve MCP documentation\n    doc-forge serve --mcp\n    ```\n\n## Project Structure\n\n- `docforge.loaders`: Introspects source code using static analysis (`griffe`).\n- `docforge.models`: The internal representation of your project, modules, and objects.\n- `docforge.renderers`: Converters that turn the models into physical files.\n- `docforge.nav`: Managers for logical-to-physical path mapping and navigation.",
+    "docstring": "Renderer-agnostic Python documentation compiler that converts docstrings into\nstructured documentation for both humans (MkDocs) and machines (MCP / AI agents).\n\n`doc-forge` statically analyzes your source code, builds a semantic model of\nmodules and objects, and renders that model into documentation outputs without\nexecuting your code.\n---\n\n# Core Philosophy\n\n`doc-forge` follows a compiler architecture:\n\n1. **Front-end (Introspection)**\n   Static analysis of modules, classes, functions, signatures, and docstrings.\n\n2. **Middle-end (Semantic Model)**\n   Renderer-neutral structured representation of your API.\n\n3. **Back-end (Renderers)**\n\n   * MkDocs → human documentation\n   * MCP JSON → AI-readable documentation\n---\n\n# Docstring Writing Standard\n\nDocstrings are the single source of truth. `doc-forge` does not generate content.\nIt compiles and renders what you write.\n\nDocumentation follows the Python import hierarchy.\n---\n\n# Package docstring (`package/__init__.py`) — Full user guide\n\nThis is the landing page. A developer must be able to install and use the\npackage after reading only this docstring.\n\n## Example:\n\n    '''\n    Short description of what this package provides.\n\n    # Installation\n\n    ```bash\n    pip install my-package\n    ```\n\n    # Quick start\n\n    ```python\n    from my_package.foo import Bar\n\n    bar = Bar()\n    result = bar.process(\"example\")\n    ```\n    ---\n\n    # Core concepts\n\n    ## Bar\n    - Primary object exposed by the package.\n\n    ## foo module\n    - Provides core functionality.\n    ---\n\n    # Typical workflow\n\n    1. Import public objects\n    2. Initialize objects\n    3. Call methods\n    ---\n\n    # Public API\n\n    foo.Bar\n    foo.helper_function\n    ---\n    '''\n---\n\n# Submodule docstring (`package/foo/__init__.py`) — Subsystem guide\n\nExplains a specific subsystem.\n\n## Example:\n\n    '''\n    Provides core functionality.\n\n    # Usage\n\n    ```python\n    from my_package.foo import Bar\n\n    bar = Bar()\n    bar.process(\"example\")\n    ```\n    ---\n    '''\n---\n\n# Class docstring — Object contract\n\nDefines responsibility and behavior.\n\n## Example:\n\n```python\nclass Bar:\n    '''\n    Performs processing on input data.\n\n    Instances may be reused across multiple calls.\n    ---\n    '''\n```\n\nInclude:\n\n* Responsibility\n* Lifecycle expectations\n* Thread safety (if relevant)\n* Performance characteristics (if relevant)\n---\n\n# Function and method docstrings — API specification\n\n## Example:\n\n```python\ndef process(\n    self,\n    value1: str,\n    value2: str | None = \"default value\",\n    value3: str | None = None,\n) -> str:\n    '''\n    Process an input value.\n    ---\n\n    Parameters\n    ----------\n    value1 : str\n        required: True\n        value to be processed\n        Example:\n            'string'\n\n    value2 : str\n        required: False\n        default: \"default value\"\n        value to be processed\n        Example:\n            'string'\n\n    value3 : str\n        required: False\n        value to be processed\n        Example:\n            'string'\n    ---\n\n    Returns\n    -------\n    processed value : str\n        result after processing value\n    ---\n\n    Behavior\n    --------\n    - behaviour 1\n    - behaviour 2\n    ---\n    '''\n```\n---\n\n# Attribute docstrings (optional)\n\n## Example:\n\n```python\nclass Class\n    '''\n    attribute1 : str\n        required: True\n        default: \"default value\"\n        attribute description\n\n    attribute2 : str\n        required: False\n        attribute description\n\n    attribute2 : str\n        required: False\n        default: \"default value\"\n        attribute description\n    '''\n\n    attribute1: str = \"default value\"\n    attribute2: str | None = None\n    attribute3: str | None = \"default value\"\n```\n---\n\n# Writing Rules\n\n**Heading hierarchy**\n\nModule docstring\n\n- Examples\n- Usage\n- Core concepts\n- Public API\n\nClass docstring\n\n- Attributes\n- Execution contract\n- Lifecycle\n- Thread safety\n- Notes\n\nMethod docstring\n\n- Parameters\n- Returns\n- Raises\n- Yields\n- Behavior\n\n**Required**\n\n* Use Markdown headings\n* Use Markdown line separator `---`\n* Line separator should be followed by a blank line\n* Provide real import examples\n* Document all public APIs\n* Keep descriptions precise and factual\n\n**Avoid**\n\n* Plain-text separators like `====`\n* Duplicate external documentation\n* Informal or conversational language\n---\n\n# How doc-forge uses these docstrings\n\n## Build MkDocs site:\n\n```bash\ndoc-forge build --mkdocs --module my_package\n```\n\n## Build MCP documentation:\n\n```bash\ndoc-forge build --mcp --module my_package\n```\n\nBoth outputs are generated directly from docstrings.\n---",
     "objects": {
       "GriffeLoader": {
         "name": "GriffeLoader",
@@ -53,7 +53,7 @@
             "kind": "function",
             "path": "docforge.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."
           }
         }
       },
@@ -275,7 +275,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."
                       }
                     }
                   },
@@ -314,7 +314,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",
@@ -455,7 +455,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/."
                   }
                 }
               },
@@ -470,22 +470,22 @@
                 "name": "build",
                 "kind": "function",
                 "path": "docforge.cli.commands.build",
-                "signature": "<bound method Function.signature of Function('build', 18, 89)>",
+                "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: 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."
+                "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)>",
+                "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    mkdocs_yml: (MkDocs) Path to the mkdocs.yml configuration.\n    out_dir: (MCP) Path to the mcp_docs/ directory."
+                "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)>",
+                "signature": "<bound method Function.signature of Function('tree', 136, 165)>",
-                "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."
+                "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",
@@ -618,8 +618,8 @@
                 "name": "serve",
                 "kind": "function",
                 "path": "docforge.cli.mcp_utils.serve",
-                "signature": "<bound method Function.signature of Function('serve', 23, 47)>",
+                "signature": "<bound method Function.signature of Function('serve', 23, 48)>",
-                "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/."
               }
             }
           },
@@ -707,7 +707,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."
                   }
                 }
               },
@@ -745,28 +745,28 @@
                 "name": "generate_sources",
                 "kind": "function",
                 "path": "docforge.cli.mkdocs_utils.generate_sources",
-                "signature": "<bound method Function.signature of Function('generate_sources', 9, 23)>",
+                "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."
+                "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."
               }
             }
@@ -2079,7 +2079,7 @@
                 "kind": "function",
                 "path": "docforge.renderers.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."
               }
             }
           },
@@ -2465,7 +2465,7 @@
             "kind": "module",
             "path": "docforge.renderers.mkdocs_renderer",
             "signature": null,
-            "docstring": "This module implements the MkDocsRenderer, which generates Markdown source files\ncompatible with the MkDocs 'material' theme and 'mkdocstrings' extension.",
+            "docstring": "MkDocsRenderer\n\nGenerates Markdown source files compatible with MkDocs Material\nand mkdocstrings, ensuring:\n\n- Root index.md always exists\n- Parent package indexes are created automatically\n- Child modules are linked in parent index files",
             "members": {
               "Path": {
                 "name": "Path",
@@ -2525,36 +2525,6 @@
                   }
                 }
               },
-              "MkDocsRenderer": {
-                "name": "MkDocsRenderer",
-                "kind": "class",
-                "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer",
-                "signature": "<bound method Class.signature of Class('MkDocsRenderer', 11, 91)>",
-                "docstring": "Renderer that generates Markdown source files formatted for the MkDocs\n'mkdocstrings' plugin.",
-                "members": {
-                  "name": {
-                    "name": "name",
-                    "kind": "attribute",
-                    "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.name",
-                    "signature": null,
-                    "docstring": null
-                  },
-                  "generate_sources": {
-                    "name": "generate_sources",
-                    "kind": "function",
-                    "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources",
-                    "signature": "<bound method Function.signature of Function('generate_sources', 19, 38)>",
-                    "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."
-                  }
-                }
-              },
-              "Set": {
-                "name": "Set",
-                "kind": "alias",
-                "path": "docforge.renderers.mkdocs_renderer.Set",
-                "signature": "<bound method Alias.signature of Alias('Set', 'typing.Set')>",
-                "docstring": null
-              },
               "Module": {
                 "name": "Module",
                 "kind": "class",
@@ -2605,6 +2575,29 @@
                     "docstring": "Get all top-level objects in the module.\n\nReturns:\n    An iterable of DocObject instances."
                   }
                 }
+              },
+              "MkDocsRenderer": {
+                "name": "MkDocsRenderer",
+                "kind": "class",
+                "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer",
+                "signature": "<bound method Class.signature of Class('MkDocsRenderer', 16, 168)>",
+                "docstring": "Renderer that generates Markdown source files formatted for the MkDocs\n'mkdocstrings' plugin.",
+                "members": {
+                  "name": {
+                    "name": "name",
+                    "kind": "attribute",
+                    "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.name",
+                    "signature": null,
+                    "docstring": null
+                  },
+                  "generate_sources": {
+                    "name": "generate_sources",
+                    "kind": "function",
+                    "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources",
+                    "signature": "<bound method Function.signature of Function('generate_sources', 27, 60)>",
+                    "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."
+                  }
+                }
               }
             }
           }

mcp_docs/modules/docforge.renderers.json

@@ -23,7 +23,7 @@
             "kind": "function",
             "path": "docforge.renderers.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."
           }
         }
       },
@@ -409,7 +409,7 @@
         "kind": "module",
         "path": "docforge.renderers.mkdocs_renderer",
         "signature": null,
-        "docstring": "This module implements the MkDocsRenderer, which generates Markdown source files\ncompatible with the MkDocs 'material' theme and 'mkdocstrings' extension.",
+        "docstring": "MkDocsRenderer\n\nGenerates Markdown source files compatible with MkDocs Material\nand mkdocstrings, ensuring:\n\n- Root index.md always exists\n- Parent package indexes are created automatically\n- Child modules are linked in parent index files",
         "members": {
           "Path": {
             "name": "Path",
@@ -469,36 +469,6 @@
               }
             }
           },
-          "MkDocsRenderer": {
-            "name": "MkDocsRenderer",
-            "kind": "class",
-            "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer",
-            "signature": "<bound method Class.signature of Class('MkDocsRenderer', 11, 91)>",
-            "docstring": "Renderer that generates Markdown source files formatted for the MkDocs\n'mkdocstrings' plugin.",
-            "members": {
-              "name": {
-                "name": "name",
-                "kind": "attribute",
-                "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.name",
-                "signature": null,
-                "docstring": null
-              },
-              "generate_sources": {
-                "name": "generate_sources",
-                "kind": "function",
-                "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources",
-                "signature": "<bound method Function.signature of Function('generate_sources', 19, 38)>",
-                "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."
-              }
-            }
-          },
-          "Set": {
-            "name": "Set",
-            "kind": "alias",
-            "path": "docforge.renderers.mkdocs_renderer.Set",
-            "signature": "<bound method Alias.signature of Alias('Set', 'typing.Set')>",
-            "docstring": null
-          },
           "Module": {
             "name": "Module",
             "kind": "class",
@@ -549,6 +519,29 @@
                 "docstring": "Get all top-level objects in the module.\n\nReturns:\n    An iterable of DocObject instances."
               }
             }
+          },
+          "MkDocsRenderer": {
+            "name": "MkDocsRenderer",
+            "kind": "class",
+            "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer",
+            "signature": "<bound method Class.signature of Class('MkDocsRenderer', 16, 168)>",
+            "docstring": "Renderer that generates Markdown source files formatted for the MkDocs\n'mkdocstrings' plugin.",
+            "members": {
+              "name": {
+                "name": "name",
+                "kind": "attribute",
+                "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.name",
+                "signature": null,
+                "docstring": null
+              },
+              "generate_sources": {
+                "name": "generate_sources",
+                "kind": "function",
+                "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources",
+                "signature": "<bound method Function.signature of Function('generate_sources', 27, 60)>",
+                "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."
+              }
+            }
           }
         }
       }

mcp_docs/modules/docforge.renderers.mkdocs_renderer.json

@@ -2,7 +2,7 @@
   "module": "docforge.renderers.mkdocs_renderer",
   "content": {
     "path": "docforge.renderers.mkdocs_renderer",
-    "docstring": "This module implements the MkDocsRenderer, which generates Markdown source files\ncompatible with the MkDocs 'material' theme and 'mkdocstrings' extension.",
+    "docstring": "MkDocsRenderer\n\nGenerates Markdown source files compatible with MkDocs Material\nand mkdocstrings, ensuring:\n\n- Root index.md always exists\n- Parent package indexes are created automatically\n- Child modules are linked in parent index files",
     "objects": {
       "Path": {
         "name": "Path",
@@ -62,36 +62,6 @@
           }
         }
       },
-      "MkDocsRenderer": {
-        "name": "MkDocsRenderer",
-        "kind": "class",
-        "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer",
-        "signature": "<bound method Class.signature of Class('MkDocsRenderer', 11, 91)>",
-        "docstring": "Renderer that generates Markdown source files formatted for the MkDocs\n'mkdocstrings' plugin.",
-        "members": {
-          "name": {
-            "name": "name",
-            "kind": "attribute",
-            "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.name",
-            "signature": null,
-            "docstring": null
-          },
-          "generate_sources": {
-            "name": "generate_sources",
-            "kind": "function",
-            "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources",
-            "signature": "<bound method Function.signature of Function('generate_sources', 19, 38)>",
-            "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."
-          }
-        }
-      },
-      "Set": {
-        "name": "Set",
-        "kind": "alias",
-        "path": "docforge.renderers.mkdocs_renderer.Set",
-        "signature": "<bound method Alias.signature of Alias('Set', 'typing.Set')>",
-        "docstring": null
-      },
       "Module": {
         "name": "Module",
         "kind": "class",
@@ -142,6 +112,29 @@
             "docstring": "Get all top-level objects in the module.\n\nReturns:\n    An iterable of DocObject instances."
           }
         }
+      },
+      "MkDocsRenderer": {
+        "name": "MkDocsRenderer",
+        "kind": "class",
+        "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer",
+        "signature": "<bound method Class.signature of Class('MkDocsRenderer', 16, 168)>",
+        "docstring": "Renderer that generates Markdown source files formatted for the MkDocs\n'mkdocstrings' plugin.",
+        "members": {
+          "name": {
+            "name": "name",
+            "kind": "attribute",
+            "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.name",
+            "signature": null,
+            "docstring": null
+          },
+          "generate_sources": {
+            "name": "generate_sources",
+            "kind": "function",
+            "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources",
+            "signature": "<bound method Function.signature of Function('generate_sources', 27, 60)>",
+            "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."
+          }
+        }
       }
     }
   }

mkdocs.yml

@@ -1,5 +1,3 @@
-site_name: docforge
-
 theme:
   name: material
   palette:
@@ -33,30 +31,34 @@ plugins:
           annotations_path: brief
           show_root_heading: true
           group_by_category: true
-
+markdown_extensions:
+- pymdownx.superfences
+- pymdownx.tabbed:
+    alternate_style: true
+site_name: docforge
 nav:
-- Home: docforge/index.md
+- Home: index.md
 - Loaders:
-  - docforge/loaders/index.md
+  - loaders/index.md
-  - docforge/loaders/griffe_loader.md
+  - loaders/griffe_loader.md
 - Models:
-  - docforge/models/index.md
+  - models/index.md
-  - docforge/models/module.md
+  - models/module.md
-  - docforge/models/object.md
+  - models/object.md
-  - docforge/models/project.md
+  - models/project.md
 - Navigation:
-  - docforge/nav/index.md
+  - nav/index.md
-  - docforge/nav/spec.md
+  - nav/spec.md
-  - docforge/nav/resolver.md
+  - nav/resolver.md
-  - docforge/nav/mkdocs.md
+  - nav/mkdocs.md
 - Renderers:
-  - docforge/renderers/index.md
+  - renderers/index.md
-  - docforge/renderers/base.md
+  - renderers/base.md
-  - docforge/renderers/mkdocs_renderer.md
+  - renderers/mkdocs_renderer.md
-  - docforge/renderers/mcp_renderer.md
+  - renderers/mcp_renderer.md
 - CLI:
-  - docforge/cli/index.md
+  - cli/index.md
-  - docforge/cli/main.md
+  - cli/main.md
-  - docforge/cli/commands.md
+  - cli/commands.md
-  - docforge/cli/mcp_utils.md
+  - cli/mcp_utils.md
-  - docforge/cli/mkdocs_utils.md
+  - cli/mkdocs_utils.md

pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "doc-forge"
-version = "0.0.3"
+version = "0.0.5"
 description = "A renderer-agnostic Python documentation compiler"
 readme = "README.md"
 requires-python = ">=3.10"

tests/cli/test_serve_mcp.py

@@ -10,7 +10,7 @@ def test_mcp_serve(
 
     result = cli_runner.invoke(
         cli,
-        ["serve", "--mcp", "--out-dir", str(fake_mcp_docs)],
+        ["serve", "--mcp", "--module", "fake_module", "--out-dir", str(fake_mcp_docs)],
     )
 
     assert result.exit_code == 0