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

Compare commits

base: aetos:google-docs
Branches Tags
aetos:main aetos:google-docs
aetos:0.0.6 aetos:0.0.5 aetos:0.0.4 aetos:0.0.3 aetos:0.0.2 aetos:0.0.1
..
compare: aetos:e8a01163fd292c268d5ed9b31978d4487983972b
Branches Tags
aetos:google-docs aetos:main
aetos:0.0.6 aetos:0.0.5 aetos:0.0.4 aetos:0.0.3 aetos:0.0.2 aetos:0.0.1

2 Commits
google-doc ... e8a01163fd

Author SHA1 Message Date
Vishesh 'ironeagle' Bangotra
e8a01163fd updated doc string for how to use 2026-01-22 16:09:39 +05:30
Vishesh 'ironeagle' Bangotra
9bccd7a82c removed ADS 2026-01-22 16:09:28 +05:30
81 changed files with 1434 additions and 3241 deletions
Expand all files Collapse all files

2
.run/pytests.run.xml → .run/pytest.run.xml
View File

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

715
README.md
View File

@@ -1,547 +1,244 @@
# docforge # doc-forge
# Summary A renderer-agnostic Python documentation compiler that converts Python source code and docstrings into a structured, semantic documentation model and emits multiple downstream representations.
Renderer-agnostic Python documentation compiler that converts Python docstrings ## Features
into structured documentation for both humans (MkDocs) and machines (MCP / AI agents).
`doc-forge` statically analyzes source code, builds a semantic model of modules, - **Single Source of Truth**: Python source code and docstrings are the only authoritative input
classes, functions, and attributes, and renders that model into documentation - **Renderer Agnosticism**: MkDocs, Sphinx, MCP, or future renderers don't influence the core model
outputs without executing user code. - **Deterministic Output**: Given the same codebase, outputs are reproducible
- **AI-Native Documentation**: Structured, queryable, and machine-consumable
- **Library-First Design**: All functionality accessible as a Python API
--- ## Installation
# Installation
Install using pip:
```bash ```bash
pip install doc-forge pip install doc-forge
``` ```
--- ### Optional Dependencies
# CLI usage
## Generate an MkDocs site from a Python package:
```bash ```bash
doc-forge build --mkdocs --module my_package # For MkDocs rendering
pip install doc-forge[mkdocs]
# For Sphinx rendering
pip install doc-forge[sphinx]
# For MCP support
pip install doc-forge[mcp]
# For development
pip install doc-forge[dev]
``` ```
## Generate MCP JSON documentation: ## Quick Start
### Command Line Interface
```bash ```bash
doc-forge build --mcp --module my_package # Generate MkDocs documentation
doc-forge generate --renderer mkdocs mypackage
# Build final HTML documentation
doc-forge build --renderer mkdocs mypackage
# Serve documentation locally
doc-forge serve --renderer mkdocs mypackage
# Export to MCP format
doc-forge export mypackage
# Start live MCP server
doc-forge server mypackage
``` ```
### Python API
## Generate MkDocs site and MCP JSON documentation: ```python
from docforge.loaders import GriffeLoader
from docforge.renderers import MkDocsRenderer
from pathlib import Path
# Load your project
loader = GriffeLoader()
project = loader.load_project(["mypackage", "mypackage.utils"])
# Generate MkDocs sources
renderer = MkDocsRenderer()
renderer.generate_sources(project, Path("docs"))
# Build final documentation
from docforge.renderers.base import RendererConfig
config = RendererConfig(Path("docs"), project)
renderer.build(config)
```
## Architecture
doc-forge follows this 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)
```
## Core Components
### Documentation Model
- **Project**: Root container for all documentation
- **Module**: Represents Python modules
- **DocObject**: Base class for classes, functions, variables, etc.
- **Navigation**: Hierarchical structure for browsing
### Renderers
- **MkDocs Renderer**: Generates Markdown with mkdocstrings directives
- **Sphinx Renderer**: Generates reStructuredText with autodoc directives
### Exporters
- **MCP Exporter**: Creates static JSON bundles for machine consumption
- **MCP Server**: Live server for real-time documentation access
## CLI Commands
### `generate`
Generate renderer-specific source files without building final artifacts.
```bash ```bash
doc-forge build --mcp --mkdocs --module my_package doc-forge generate --renderer mkdocs --out-dir docs mypackage
``` ```
## Serve MkDocs locally: ### `build`
Build final documentation artifacts (HTML, etc.).
```bash ```bash
doc-forge serve --mkdocs --module my_package doc-forge build --renderer sphinx mypackage
``` ```
## Serve MCP locally: ### `serve`
Start a local development server.
```bash ```bash
doc-forge serve --mcp --module my_package doc-forge serve --renderer mkdocs --port 9000 mypackage
``` ```
--- ### `export`
Export to MCP format for machine consumption.
# Core concepts ```bash
doc-forge export --out-dir mcp mypackage
## Loader
Extracts symbols, signatures, and docstrings using static analysis.
## Semantic model
Structured, renderer-agnostic representation of the API.
## Renderer
Converts the semantic model into output formats such as MkDocs or MCP JSON.
## Symbol
Any documentable object
- module
- class
- function
- method
- property
- attribute
---
# Architecture
`doc-forge` follows a compiler architecture:
## Front-end:
Static analysis of modules, classes, functions, type hints, and docstrings.
## Middle-end:
Builds a semantic model describing symbols and relationships.
## Back-end:
Renders documentation using interchangeable renderers.
This architecture ensures deterministic documentation generation.
---
# Rendering pipeline
Typical flow:
Python package
|
Loader (static analysis)
|
Semantic model
|
Renderer
|
MkDocs site or MCP JSON
---
# Google-Styled Doc-Forge Convention (GSDFC)
GSDFC defines how docstrings must be written so they render correctly in MkDocs and remain machine-parsable by doc-forge and AI tooling.
- Docstrings are the single source of truth.
- `doc-forge` compiles docstrings but does not generate documentation content.
- Documentation follows the Python import hierarchy.
- Every public symbol should have a complete and accurate docstring.
---
## General rules
- Use **Markdown headings** at package and module level.
- Use **Google-style structured sections** at class, function, and method level.
- Use type hints in signatures instead of duplicating types in prose.
- Write summaries in imperative form.
- Sections are separated by `---`
---
# Notes subsection grouping
Group related information using labeled subsections.
Example:
Notes:
**Guarantees:**
- deterministic behavior
**Lifecycle:**
- created during initialization
- reused across executions
**Thread safety:**
- safe for concurrent reads
---
# Example formatting
- Use indentation for examples.
- Indent section contents using four spaces.
- Use code blocks for example code.
Example:
Single example:
Example:
```python
foo = Foo("example")
process(foo, multiplier=2)
```
Multiple examples:
Example:
Create foo:
```python
foo = Foo("example")
```
Run engine:
```python
engine = BarEngine([foo])
engine.run()
```
Avoid fenced code blocks inside structured sections.
---
# Separator rules
Use horizontal separators only at docstring root level to separate sections:
```markdown
---
``` ```
Allowed locations: ### `server`
Start live MCP server for real-time access.
- package docstrings ```bash
- module docstrings doc-forge server --host 0.0.0.0 --port 8080 mypackage
- major documentation sections ```
Do not use separators inside code sections. ## Configuration
doc-forge is designed to work with minimal configuration. Most settings are derived automatically from your Python code structure.
### MkDocs Configuration
The MkDocs renderer automatically generates `mkdocs.yml` with sensible defaults:
```yaml
site_name: Your Project
plugins:
- mkdocstrings
theme:
name: material
```
### Sphinx Configuration
The Sphinx renderer automatically generates `conf.py` with standard extensions:
```python
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.viewcode',
'sphinx.ext.napoleon',
]
```
## MCP Integration
doc-forge provides two ways to integrate with MCP (Model Context Protocol):
### Static Export
```bash
doc-forge export mypackage
```
Creates a static JSON bundle in `mcp/` directory that can be loaded by MCP clients.
### Live Server
```bash
doc-forge server mypackage
```
Starts a live MCP server providing real-time access to documentation resources:
- `docs://index` - Project metadata
- `docs://nav` - Navigation structure
- `docs://module/{module}` - Individual module data
## Development
### Setup
```bash
git clone https://github.com/doc-forge/doc-forge
cd doc-forge
pip install -e ".[dev]"
```
### Running Tests
```bash
pytest
```
### Code Quality
```bash
black docforge/
ruff check docforge/
mypy docforge/
```
## License
MIT License - see LICENSE file for details.
## Contributing
Contributions are welcome! Please see CONTRIBUTING.md for guidelines.
## Philosophy
doc-forge is built on these core principles:
1. **Single Source of Truth**: Python source code and docstrings are the only authoritative input
2. **Renderer Agnosticism**: The core model contains no renderer-specific logic
3. **Deterministic Output**: Same input always produces same output
4. **AI-Native Documentation**: Documentation must be structured, queryable, and machine-consumable
5. **Library-First**: All functionality must be accessible as a Python API
--- ---
# Package docstrings *doc-forge turns Python code into structured knowledge and emits it through multiple human and machine interfaces.*
Package docstrings act as the documentation home page.
Recommended sections:
# Summary
# Installation
# Quick start
# CLI usage
# Core concepts
# Architecture
# Rendering pipeline
# Examples
# Notes
Example:
Package Doc String:
'''
# Summary
Foo-bar processing framework.
Provides tools for defining Foo objects and executing Bar pipelines.
---
# Installation
```bash
pip install foo-bar
```
---
# Quick start
```python
from foobar import Foo, BarEngine
foo = Foo("example")
engine = BarEngine([foo])
result = engine.run()
```
---
'''
---
# Module docstrings
Module docstrings describe a subsystem.
Recommended sections:
# Summary
# Examples
# Notes
Example:
Module Doc String:
'''
# Summary
Foo execution subsystem.
Provides utilities for executing Foo objects through Bar stages.
---
Example:
```python
from foobar.engine import BarEngine
from foobar.foo import Foo
foo = Foo("example")
engine = BarEngine([foo])
engine.run()
```
---
'''
---
# Class docstrings
Class docstrings define object responsibility, lifecycle, and attributes.
Recommended sections:
Attributes:
Notes:
Example:
Raises:
Example:
Simple Foo:
```python
class Foo:
'''
Represents a unit of work.
Attributes:
name (str):
Identifier of the foo instance.
value (int):
Numeric value associated with foo.
Notes:
Guarantees:
- instances are immutable after creation
Lifecycle:
- create instance
- pass to processing engine
Example:
Create and inspect a Foo:
```python
foo = Foo("example", value=42)
print(foo.name)
```
'''
```
Complex Bar:
```python
class BarEngine:
'''
Executes Foo objects through Bar stages.
Attributes:
foos (tuple[Foo, ...]):
Foo instances managed by the engine.
Notes:
Guarantees:
- deterministic execution order
Example:
Run engine:
```python
foo1 = Foo("a")
foo2 = Foo("b")
engine = BarEngine([foo1, foo2])
engine.run()
```
'''
```
---
# Function and method docstrings
Function docstrings define API contracts.
Recommended sections:
Args:
Returns:
Raises:
Yields:
Notes:
Example:
Example:
Simple process method:
```python
def process(foo: Foo, multiplier: int) -> int:
'''
Process a Foo instance.
Args:
foo (Foo):
Foo instance to process.
multiplier (int):
Value used to scale foo.
Returns:
int:
Processed result.
Raises:
ValueError:
If multiplier is negative.
Notes:
Guarantees:
- foo is not modified
Example:
Process foo:
```python
foo = Foo("example", value=10)
result = process(foo, multiplier=2)
print(result)
```
'''
```
Multiple Examples:
```python
def combine(foo_a: Foo, foo_b: Foo) -> Foo:
'''
Combine two Foo instances.
Args:
foo_a (Foo):
First foo.
foo_b (Foo):
Second foo.
Returns:
Foo:
Combined foo.
Example:
Basic usage:
```python
foo1 = Foo("a")
foo2 = Foo("b")
combined = combine(foo1, foo2)
```
Pipeline usage:
```python
engine = BarEngine([foo1, foo2])
engine.run()
```
'''
```
---
# Property docstrings
Properties must document return values.
Example:
Property Doc String:
```python
@property
def foos(self) -> tuple[Foo, ...]:
'''
Return contained Foo instances.
Returns:
tuple[Foo, ...]:
Stored foo objects.
Example:
```python
container = FooContainer()
foos = container.foos
```
'''
```
---
# Attribute documentation
Document attributes in class docstrings using `Attributes:`.
Example:
Attribute Doc String:
```python
'''
Represents a processing stage.
Attributes:
id (str):
Unique identifier.
enabled (bool):
Whether the stage is active.
'''
```
---
# Parsing guarantees
GSDFC ensures doc-forge can deterministically extract:
- symbol kind (module, class, function, property, attribute)
- symbol name
- parameters
- return values
- attributes
- examples
- structured Notes subsections
This enables:
- reliable MkDocs rendering
- deterministic MCP export
- accurate AI semantic interpretation
---
Notes:
- doc-forge never executes analyzed modules.
- Documentation is generated entirely through static analysis.

40
docforge.nav.yml
View File

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

587
docforge/__init__.py
View File

@@ -1,549 +1,86 @@
""" """
# Summary # doc-forge
Renderer-agnostic Python documentation compiler that converts Python docstrings `doc-forge` is a renderer-agnostic Python documentation compiler designed for
into structured documentation for both humans (MkDocs) and machines (MCP / AI agents). speed, flexibility, and beautiful output. It decouples the introspection of
your code from the rendering process, allowing you to generate documentation
for various platforms (starting with MkDocs) from a single internal models.
`doc-forge` statically analyzes source code, builds a semantic model of modules, ## Core Philosophy
classes, functions, and attributes, and renders that model into documentation
outputs without executing user code.
--- `doc-forge` operates on two fundamental principles:
# Installation 1. **The Atomic Unit is a Python Import Path**: Documentation is organized around the semantic structure of your code (e.g., `mypackage.utils`), not the filesystem.
2. **The Documentation Compiler Paradigm**: We separate documentation into three distinct phases:
- **Front-end (Introspection)**: Static analysis of source code and docstrings.
- **Middle-end (Semantic Model)**: A renderer-neutral internal representation.
- **Back-end (Renderers)**: Generation of human-facing (MkDocs) or machine-facing (MCP) outputs.
Install using pip: ## Documentation Design
`doc-forge` is an "AI-Native" documentation compiler. To get the most out of it, design your docstrings with both humans and LLMs in mind:
### For Humans (Readability & Structure)
- **`__init__.py` as Landing Pages**: Use the docstring of your package's `__init__.py` as the home page. Include overviews, installation instructions, and high-level examples here.
- **Single Source of Truth**: Keep all technical details in docstrings. This ensures your MkDocs/Sphinx sites stay in sync with the code.
- **Semantic Hierarchy**: Use standard Markdown headers to structure complex module documentation.
### For LLMs (AI-Native Knowledge)
- **Model Context Protocol (MCP)**: `doc-forge` exports your docs as structured JSON. This allows AI agents to "understand" your API surface area without layout noise.
- **Canonical Paths**: Use dotted import paths as primary identifiers. AI tools use these to link code usage to documentation.
- **Type Annotations**: While not in docstrings, `doc-forge` (via Griffe) extracts signatures. Clean type hints dramatically improve an LLM's ability to generate correct code using your library.
## Available Commands
- **build**: Build documentation (MkDocs site or MCP resources).
- **serve**: Serve documentation (MkDocs or MCP).
- **tree**: Visualize the introspected project structure.
## Installation
Install using `pip` with the optional `mkdocs` dependencies for a complete setup:
```bash ```bash
pip install doc-forge pip install doc-forge
``` ```
--- ## Quick Start
# CLI usage 1. **Build Documentation**:
Introspect your package and generate documentation in one step:
```bash
# Build MkDocs site
doc-forge build --mkdocs --module my_package --site-name "My Docs"
## Generate an MkDocs site from a Python package: # Build MCP resources
doc-forge build --mcp --module my_package
```bash
doc-forge build --mkdocs --module my_package
```
## Generate MCP JSON documentation:
```bash
doc-forge build --mcp --module my_package
```
## Generate MkDocs site and MCP JSON documentation:
```bash
doc-forge build --mcp --mkdocs --module my_package
```
## Serve MkDocs locally:
```bash
doc-forge serve --mkdocs --module my_package
```
## Serve MCP locally:
```bash
doc-forge serve --mcp --module my_package
```
---
# Core concepts
## Loader
Extracts symbols, signatures, and docstrings using static analysis.
## Semantic model
Structured, renderer-agnostic representation of the API.
## Renderer
Converts the semantic model into output formats such as MkDocs or MCP JSON.
## Symbol
Any documentable object
- module
- class
- function
- method
- property
- attribute
---
# Architecture
`doc-forge` follows a compiler architecture:
## Front-end:
Static analysis of modules, classes, functions, type hints, and docstrings.
## Middle-end:
Builds a semantic model describing symbols and relationships.
## Back-end:
Renders documentation using interchangeable renderers.
This architecture ensures deterministic documentation generation.
---
# Rendering pipeline
Typical flow:
Python package
|
Loader (static analysis)
|
Semantic model
|
Renderer
|
MkDocs site or MCP JSON
---
# Google-Styled Doc-Forge Convention (GSDFC)
GSDFC defines how docstrings must be written so they render correctly in MkDocs and remain machine-parsable by doc-forge and AI tooling.
- Docstrings are the single source of truth.
- `doc-forge` compiles docstrings but does not generate documentation content.
- Documentation follows the Python import hierarchy.
- Every public symbol should have a complete and accurate docstring.
---
## General rules
- Use **Markdown headings** at package and module level.
- Use **Google-style structured sections** at class, function, and method level.
- Use type hints in signatures instead of duplicating types in prose.
- Write summaries in imperative form.
- Sections are separated by `---`
---
# Notes subsection grouping
Group related information using labeled subsections.
Example:
Notes:
**Guarantees:**
- deterministic behavior
**Lifecycle:**
- created during initialization
- reused across executions
**Thread safety:**
- safe for concurrent reads
---
# Example formatting
- Use indentation for examples.
- Indent section contents using four spaces.
- Use code blocks for example code.
Example:
Single example:
Example:
```python
foo = Foo("example")
process(foo, multiplier=2)
```
Multiple examples:
Example:
Create foo:
```python
foo = Foo("example")
```
Run engine:
```python
engine = BarEngine([foo])
engine.run()
```
Avoid fenced code blocks inside structured sections.
---
# Separator rules
Use horizontal separators only at docstring root level to separate sections:
```markdown
---
```
Allowed locations:
- package docstrings
- module docstrings
- major documentation sections
Do not use separators inside code sections.
---
# Package docstrings
Package docstrings act as the documentation home page.
Recommended sections:
# Summary
# Installation
# Quick start
# CLI usage
# Core concepts
# Architecture
# Rendering pipeline
# Examples
# Notes
Example:
Package Doc String:
'''
# Summary
Foo-bar processing framework.
Provides tools for defining Foo objects and executing Bar pipelines.
---
# Installation
```bash
pip install foo-bar
```
---
# Quick start
```python
from foobar import Foo, BarEngine
foo = Foo("example")
engine = BarEngine([foo])
result = engine.run()
```
---
'''
---
# Module docstrings
Module docstrings describe a subsystem.
Recommended sections:
# Summary
# Examples
# Notes
Example:
Module Doc String:
'''
# Summary
Foo execution subsystem.
Provides utilities for executing Foo objects through Bar stages.
---
Example:
```python
from foobar.engine import BarEngine
from foobar.foo import Foo
foo = Foo("example")
engine = BarEngine([foo])
engine.run()
```
---
'''
---
# Class docstrings
Class docstrings define object responsibility, lifecycle, and attributes.
Recommended sections:
Attributes:
Notes:
Example:
Raises:
Example:
Simple Foo:
```python
class Foo:
'''
Represents a unit of work.
Attributes:
name (str):
Identifier of the foo instance.
value (int):
Numeric value associated with foo.
Notes:
Guarantees:
- instances are immutable after creation
Lifecycle:
- create instance
- pass to processing engine
Example:
Create and inspect a Foo:
```python
foo = Foo("example", value=42)
print(foo.name)
```
'''
``` ```
Complex Bar: 2. **Define Navigation**:
Create a `docforge.nav.yml` to organize your documentation:
```python ```yaml
class BarEngine: home: my_package/index.md
''' groups:
Executes Foo objects through Bar stages. Core API:
- my_package/core/*.md
Attributes: Utilities:
foos (tuple[Foo, ...]): - my_package/utils.md
Foo instances managed by the engine.
Notes:
Guarantees:
- deterministic execution order
Example:
Run engine:
```python
foo1 = Foo("a")
foo2 = Foo("b")
engine = BarEngine([foo1, foo2])
engine.run()
```
'''
``` ```
--- 3. **Preview**:
```bash
# Serve MkDocs site
doc-forge serve --mkdocs
# Function and method docstrings # Serve MCP documentation
doc-forge serve --mcp
Function docstrings define API contracts.
Recommended sections:
Args:
Returns:
Raises:
Yields:
Notes:
Example:
Example:
Simple process method:
```python
def process(foo: Foo, multiplier: int) -> int:
'''
Process a Foo instance.
Args:
foo (Foo):
Foo instance to process.
multiplier (int):
Value used to scale foo.
Returns:
int:
Processed result.
Raises:
ValueError:
If multiplier is negative.
Notes:
Guarantees:
- foo is not modified
Example:
Process foo:
```python
foo = Foo("example", value=10)
result = process(foo, multiplier=2)
print(result)
```
'''
``` ```
Multiple Examples: ## Project Structure
```python - `docforge.loaders`: Introspects source code using static analysis (`griffe`).
def combine(foo_a: Foo, foo_b: Foo) -> Foo: - `docforge.models`: The internal representation of your project, modules, and objects.
''' - `docforge.renderers`: Converters that turn the models into physical files.
Combine two Foo instances. - `docforge.nav`: Managers for logical-to-physical path mapping and navigation.
Args:
foo_a (Foo):
First foo.
foo_b (Foo):
Second foo.
Returns:
Foo:
Combined foo.
Example:
Basic usage:
```python
foo1 = Foo("a")
foo2 = Foo("b")
combined = combine(foo1, foo2)
```
Pipeline usage:
```python
engine = BarEngine([foo1, foo2])
engine.run()
```
'''
```
---
# Property docstrings
Properties must document return values.
Example:
Property Doc String:
```python
@property
def foos(self) -> tuple[Foo, ...]:
'''
Return contained Foo instances.
Returns:
tuple[Foo, ...]:
Stored foo objects.
Example:
```python
container = FooContainer()
foos = container.foos
```
'''
```
---
# Attribute documentation
Document attributes in class docstrings using `Attributes:`.
Example:
Attribute Doc String:
```python
'''
Represents a processing stage.
Attributes:
id (str):
Unique identifier.
enabled (bool):
Whether the stage is active.
'''
```
---
# Parsing guarantees
GSDFC ensures doc-forge can deterministically extract:
- symbol kind (module, class, function, property, attribute)
- symbol name
- parameters
- return values
- attributes
- examples
- structured Notes subsections
This enables:
- reliable MkDocs rendering
- deterministic MCP export
- accurate AI semantic interpretation
---
Notes:
- doc-forge never executes analyzed modules.
- Documentation is generated entirely through static analysis.
""" """
from .loaders import GriffeLoader, discover_module_paths from .loaders import GriffeLoader, discover_module_paths

38
docforge/cli/__init__.py
View File

@@ -1,38 +1,14 @@
""" """
# Summary # CLI Layer
Command line interface entry point for doc-forge. The `docforge.cli` package provides the command-line interface for interacting
with doc-forge.
This module exposes the primary CLI entry function used by the ## Available Commands
`doc-forge` command. The actual command implementation resides in
`docforge.cli.main`, while this module provides a stable import path
for external tools and the package entry point configuration.
The CLI is responsible for orchestrating documentation workflows such as - **build**: Build documentation (MkDocs site or MCP resources).
generating renderer sources, building documentation sites, exporting - **serve**: Serve documentation (MkDocs or MCP).
machine-readable documentation bundles, and starting development or MCP - **tree**: Visualize the introspected project structure.
servers.
---
# Typical usage
The CLI is normally invoked through the installed command:
```bash
doc-forge <command> [options]
```
Programmatic invocation is also possible:
Example:
```python
from docforge.cli import main
main()
```
---
""" """
from .main import main from .main import main

158
docforge/cli/commands.py
View File

@@ -1,11 +1,3 @@
"""
# Summary
Command definitions for the doc-forge CLI.
Provides the CLI structure using Click, including build, serve, and tree commands.
"""
import click import click
from pathlib import Path from pathlib import Path
from typing import Sequence, Optional from typing import Sequence, Optional
@@ -17,10 +9,8 @@ from docforge.cli import mcp_utils
@click.group() @click.group()
def cli() -> None: def cli() -> None:
""" """
Root command group for the doc-forge CLI. doc-forge CLI: A tool for introspecting Python projects and generating
documentation.
Provides commands for building, serving, and inspecting
documentation generated from Python source code.
""" """
pass pass
@@ -28,20 +18,20 @@ def cli() -> None:
@cli.command() @cli.command()
@click.option("--mcp", is_flag=True, help="Build MCP resources") @click.option("--mcp", is_flag=True, help="Build MCP resources")
@click.option("--mkdocs", is_flag=True, help="Build MkDocs site") @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("--module", help="Python module to document")
@click.option("--project-name", help="Project name override") @click.option("--project-name", help="Project name override")
# MkDocs specific
@click.option("--site-name", help="MkDocs site name") @click.option("--site-name", help="MkDocs site name")
@click.option("--docs-dir", type=click.Path(path_type=Path), default=Path("docs"), help="Directory for MD sources") @click.option("--docs-dir", type=click.Path(path_type=Path), default=Path("docs"), help="Directory for MD sources")
@click.option("--nav", "nav_file", type=click.Path(path_type=Path), default=Path("docforge.nav.yml"), @click.option("--nav", "nav_file", type=click.Path(path_type=Path), default=Path("docforge.nav.yml"),
help="Nav spec path") help="Nav spec path")
@click.option("--template", type=click.Path(path_type=Path), help="MkDocs template path") @click.option("--template", type=click.Path(path_type=Path), help="MkDocs template path")
@click.option("--mkdocs-yml", type=click.Path(path_type=Path), default=Path("mkdocs.yml"), help="Output config path") @click.option("--mkdocs-yml", type=click.Path(path_type=Path), default=Path("mkdocs.yml"), help="Output config path")
# MCP specific
@click.option("--out-dir", type=click.Path(path_type=Path), default=Path("mcp_docs"), help="MCP output directory") @click.option("--out-dir", type=click.Path(path_type=Path), default=Path("mcp_docs"), help="MCP output directory")
def build( def build(
mcp: bool, mcp: bool,
mkdocs: bool, mkdocs: bool,
module_is_source: bool,
module: Optional[str], module: Optional[str],
project_name: Optional[str], project_name: Optional[str],
site_name: Optional[str], site_name: Optional[str],
@@ -52,56 +42,24 @@ def build(
out_dir: Path, out_dir: Path,
) -> None: ) -> None:
""" """
Build documentation artifacts. Build documentation (MkDocs site or MCP resources).
This command performs the full documentation build pipeline: This command orchestrates the full build process:
1. Introspects the code (Griffe)
1. Introspects the Python project using Griffe 2. Renders sources (MkDocs Markdown or MCP JSON)
2. Generates renderer-specific documentation sources 3. (MkDocs only) Generates config and runs the final site build.
3. Optionally builds the final documentation output
Depending on the selected options, the build can target:
- MkDocs static documentation sites
- MCP structured documentation resources
Args: Args:
mcp (bool): mcp: Use the MCP documentation builder.
Enable MCP documentation generation. mkdocs: Use the MkDocs documentation builder.
module: The dotted path of the module to document.
mkdocs (bool): project_name: Optional override for the project name.
Enable MkDocs documentation generation. site_name: (MkDocs) The site display name. Defaults to module name.
docs_dir: (MkDocs) Target directory for Markdown sources.
module_is_source (bool): nav_file: (MkDocs) Path to the docforge.nav.yml specification.
Treat the specified module directory as the project root. template: (MkDocs) Optional custom mkdocs.yml template.
mkdocs_yml: (MkDocs) Target path for the generated mkdocs.yml.
module (Optional[str]): out_dir: (MCP) Target directory for MCP JSON resources.
Python module import path to document.
project_name (Optional[str]):
Optional override for the project name.
site_name (Optional[str]):
Display name for the MkDocs site.
docs_dir (Path):
Directory where Markdown documentation sources will be generated.
nav_file (Path):
Path to the navigation specification file.
template (Optional[Path]):
Optional custom MkDocs configuration template.
mkdocs_yml (Path):
Output path for the generated MkDocs configuration.
out_dir (Path):
Output directory for generated MCP resources.
Raises:
click.UsageError:
If required options are missing or conflicting.
""" """
if not mcp and not mkdocs: if not mcp and not mkdocs:
raise click.UsageError("Must specify either --mcp or --mkdocs") raise click.UsageError("Must specify either --mcp or --mkdocs")
@@ -113,12 +71,7 @@ def build(
site_name = module site_name = module
click.echo(f"Generating MkDocs sources in {docs_dir}...") click.echo(f"Generating MkDocs sources in {docs_dir}...")
mkdocs_utils.generate_sources( mkdocs_utils.generate_sources(module, project_name, docs_dir)
module,
docs_dir,
project_name,
module_is_source,
)
click.echo(f"Generating MkDocs config {mkdocs_yml}...") click.echo(f"Generating MkDocs config {mkdocs_yml}...")
mkdocs_utils.generate_config(docs_dir, nav_file, template, mkdocs_yml, site_name) mkdocs_utils.generate_config(docs_dir, nav_file, template, mkdocs_yml, site_name)
@@ -139,87 +92,58 @@ def build(
@cli.command() @cli.command()
@click.option("--mcp", is_flag=True, help="Serve MCP documentation") @click.option("--mcp", is_flag=True, help="Serve MCP documentation")
@click.option("--mkdocs", is_flag=True, help="Serve MkDocs site") @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("--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") @click.option("--out-dir", type=click.Path(path_type=Path), default=Path("mcp_docs"), help="MCP root directory")
def serve( def serve(
mcp: bool, mcp: bool,
mkdocs: bool, mkdocs: bool,
module: Optional[str],
mkdocs_yml: Path, mkdocs_yml: Path,
out_dir: Path, out_dir: Path,
) -> None: ) -> None:
""" """
Serve generated documentation locally. Serve documentation (MkDocs or MCP).
Depending on the selected mode, this command starts either:
- A MkDocs development server for browsing documentation
- An MCP server exposing structured documentation resources
Args: Args:
mcp (bool): mcp: Serve MCP resources via an MCP server.
Serve documentation using the MCP server. mkdocs: Serve the MkDocs site using the built-in development server.
mkdocs_yml: (MkDocs) Path to the mkdocs.yml configuration.
mkdocs (bool): out_dir: (MCP) Path to the mcp_docs/ directory.
Serve the MkDocs development site.
module (Optional[str]):
Python module import path to serve via MCP.
mkdocs_yml (Path):
Path to the MkDocs configuration file.
out_dir (Path):
Root directory containing MCP documentation resources.
Raises:
click.UsageError:
If invalid or conflicting options are provided.
""" """
if mcp and mkdocs: if mcp and mkdocs:
raise click.UsageError("Cannot specify both --mcp and --mkdocs") raise click.UsageError("Cannot specify both --mcp and --mkdocs")
if not mcp and not mkdocs: if not mcp and not mkdocs:
raise click.UsageError("Must specify either --mcp or --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: if mkdocs:
mkdocs_utils.serve(mkdocs_yml) mkdocs_utils.serve(mkdocs_yml)
elif mcp: elif mcp:
mcp_utils.serve(module, out_dir) mcp_utils.serve(out_dir)
@cli.command() @cli.command()
@click.option( @click.option(
"--module", "--modules",
multiple=True,
required=True, required=True,
help="Python module import path to introspect", help="Python module import paths to introspect",
) )
@click.option( @click.option(
"--project-name", "--project-name",
help="Project name (defaults to specified module)", help="Project name (defaults to first module)",
) )
def tree( def tree(
module: str, modules: Sequence[str],
project_name: Optional[str], project_name: Optional[str],
) -> None: ) -> None:
""" """
Display the documentation object tree for a module. Visualize the project structure in the terminal.
This command introspects the specified module and prints a
hierarchical representation of the discovered documentation
objects, including modules, classes, functions, and members.
Args: Args:
module (str): modules: List of module import paths to recursively introspect.
Python module import path to introspect. project_name: Optional override for the project name shown at the root.
project_name (Optional[str]):
Optional name to display as the project root.
""" """
loader = GriffeLoader() loader = GriffeLoader()
project = loader.load_project([module], project_name) project = loader.load_project(list(modules), project_name)
click.echo(project.name) click.echo(project.name)
@@ -231,17 +155,11 @@ def tree(
def _print_object(obj, indent: str) -> None: def _print_object(obj, indent: str) -> None:
""" """
Recursively print a documentation object and its members. Recursive helper to print doc objects and their members to the console.
This helper function traverses the documentation object graph
and prints each object with indentation to represent hierarchy.
Args: Args:
obj: obj: The DocObject instance to print.
Documentation object to print. indent: Current line indentation (e.g., '│ ').
indent (str):
Current indentation prefix used for nested members.
""" """
click.echo(f"{indent}├── {obj.name}") click.echo(f"{indent}├── {obj.name}")
for member in obj.get_all_members(): for member in obj.get_all_members():

4
docforge/cli/commands.pyi
View File

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

19
docforge/cli/main.py
View File

@@ -1,25 +1,14 @@
""" """
# Summary Main entry point for the doc-forge CLI. This module delegates all command
execution to docforge.cli.commands.
Command-line entry point for the doc-forge CLI.
This module exposes the executable entry point that initializes the
Click command group defined in `docforge.cli.commands`.
""" """
from docforge.cli.commands import cli from docforge.cli.commands import cli
def main() -> None: def main() -> None:
""" """
Run the doc-forge command-line interface. CLI Entry point. Boots the click application.
This function initializes and executes the Click CLI application.
It is used as the console entry point when invoking `doc-forge`
from the command line.
""" """
cli() cli()
if __name__ == "__main__": if __name__ == "__main__":
main() main()

49
docforge/cli/mcp_utils.py
View File

@@ -1,36 +1,17 @@
"""
# Summary
Utilities for working with MCP in the doc-forge CLI.
"""
from pathlib import Path from pathlib import Path
import click import click
from docforge.loaders import GriffeLoader, discover_module_paths from docforge.loaders import GriffeLoader, discover_module_paths
from docforge.renderers import MCPRenderer from docforge.renderers import MCPRenderer
from docforge.servers import MCPServer from docforge.servers import MCPServer
def generate_resources(module: str, project_name: str | None, out_dir: Path) -> None: def generate_resources(module: str, project_name: str | None, out_dir: Path) -> None:
""" """
Generate MCP documentation resources from a Python module. Generate MCP-compatible documentation resources.
The function performs project introspection, builds the internal
documentation model, and renders MCP-compatible JSON resources
to the specified output directory.
Args: Args:
module (str): module: The dotted path of the primary module to document.
Python module import path used as the entry point for project_name: Optional override for the project name.
documentation generation. out_dir: Directory where the MCP JSON resources and nav will be written.
project_name (Optional[str]):
Optional override for the project name used in generated
documentation metadata.
out_dir (Path):
Directory where MCP resources (index.json, nav.json, and module data)
will be written.
""" """
loader = GriffeLoader() loader = GriffeLoader()
discovered_paths = discover_module_paths(module) discovered_paths = discover_module_paths(module)
@@ -39,26 +20,12 @@ def generate_resources(module: str, project_name: str | None, out_dir: Path) ->
renderer = MCPRenderer() renderer = MCPRenderer()
renderer.generate_sources(project, out_dir) renderer.generate_sources(project, out_dir)
def serve(mcp_root: Path) -> None:
def serve(module: str, mcp_root: Path) -> None:
""" """
Start an MCP server for a pre-generated documentation bundle. Serve MCP documentation from a pre-built bundle.
The server exposes documentation resources such as project metadata,
navigation structure, and module documentation through MCP endpoints.
Args: Args:
module (str): mcp_root: Path to the directory containing index.json, nav.json, and modules/.
Python module import path used to identify the served
documentation instance.
mcp_root (Path):
Path to the directory containing the MCP documentation
bundle (index.json, nav.json, and modules/).
Raises:
click.ClickException:
If the MCP documentation bundle is missing required files or directories.
""" """
if not mcp_root.exists(): if not mcp_root.exists():
raise click.ClickException(f"mcp_docs directory not found: {mcp_root}") raise click.ClickException(f"mcp_docs directory not found: {mcp_root}")
@@ -75,6 +42,6 @@ def serve(module: str, mcp_root: Path) -> None:
server = MCPServer( server = MCPServer(
mcp_root=mcp_root, mcp_root=mcp_root,
name=f"{module}-mcp", name="doc-forge-mcp",
) )
server.run() server.run()

2
docforge/cli/mcp_utils.pyi
View File

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

113
docforge/cli/mkdocs_utils.py
View File

@@ -1,9 +1,3 @@
"""
# Summary
Utilities for working with MkDocs in the doc-forge CLI.
"""
from pathlib import Path from pathlib import Path
from importlib import resources from importlib import resources
import click import click
@@ -12,87 +6,32 @@ from docforge.loaders import GriffeLoader, discover_module_paths
from docforge.renderers import MkDocsRenderer from docforge.renderers import MkDocsRenderer
from docforge.nav import load_nav_spec, resolve_nav, MkDocsNavEmitter 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 MkDocs Markdown sources for a Python module. Generate Markdown source files for the specified module.
This function introspects the specified module, builds the internal
documentation model, and renders Markdown documentation files for
use with MkDocs.
Args: Args:
module (str): module: The dotted path of the primary module to document.
Python module import path used as the entry point for project_name: Optional override for the project name.
documentation generation. docs_dir: Directory where the generated Markdown files will be written.
docs_dir (Path):
Directory where the generated Markdown files will be written.
project_name (Optional[str]):
Optional override for the project name used in documentation metadata.
module_is_source (Optional[bool]):
If True, treat the specified module directory as the project root
rather than a nested module.
""" """
loader = GriffeLoader() loader = GriffeLoader()
discovered_paths = discover_module_paths(module) discovered_paths = discover_module_paths(module)
project = loader.load_project(discovered_paths, project_name) project = loader.load_project(discovered_paths, project_name)
renderer = MkDocsRenderer() renderer = MkDocsRenderer()
renderer.generate_sources( renderer.generate_sources(project, docs_dir)
project,
docs_dir,
module_is_source,
)
renderer.generate_readme( def generate_config(docs_dir: Path, nav_file: Path, template: Path | None, out: Path, site_name: str) -> None:
project,
docs_dir,
module_is_source,
)
def generate_config(
docs_dir: Path,
nav_file: Path,
template: Path | None,
out: Path,
site_name: str,
) -> None:
""" """
Generate an `mkdocs.yml` configuration file. Generate an mkdocs.yml configuration file.
The configuration is created by combining a template configuration
with a navigation structure derived from the docforge navigation
specification.
Args: Args:
docs_dir (Path): docs_dir: Path to the directory containing documentation Markdown files.
Directory containing generated documentation Markdown files. nav_file: Path to the docforge.nav.yml specification.
template: Optional path to an mkdocs.yml template (overrides built-in).
nav_file (Path): out: Path where the final mkdocs.yml will be written.
Path to the `docforge.nav.yml` navigation specification. site_name: The display name for the documentation site.
template (Optional[Path]):
Optional path to a custom MkDocs configuration template. If not
provided, a built-in template will be used.
out (Path):
Destination path where the generated `mkdocs.yml` file will be written.
site_name (str):
Display name for the generated documentation site.
Raises:
click.FileError:
If the navigation specification or template file cannot be found.
""" """
if not nav_file.exists(): if not nav_file.exists():
raise click.FileError(str(nav_file), hint="Nav spec not found") raise click.FileError(str(nav_file), hint="Nav spec not found")
@@ -119,21 +58,12 @@ def generate_config(
out.write_text(yaml.safe_dump(data, sort_keys=False), encoding="utf-8") out.write_text(yaml.safe_dump(data, sort_keys=False), encoding="utf-8")
def build(mkdocs_yml: Path) -> None: def build(mkdocs_yml: Path) -> None:
""" """
Build the MkDocs documentation site. Build the documentation site using MkDocs.
This function loads the MkDocs configuration and runs the MkDocs
build command to generate the final static documentation site.
Args: Args:
mkdocs_yml (Path): mkdocs_yml: Path to the mkdocs.yml configuration file.
Path to the `mkdocs.yml` configuration file.
Raises:
click.ClickException:
If the configuration file does not exist.
""" """
if not mkdocs_yml.exists(): if not mkdocs_yml.exists():
raise click.ClickException(f"mkdocs.yml not found: {mkdocs_yml}") raise click.ClickException(f"mkdocs.yml not found: {mkdocs_yml}")
@@ -143,21 +73,12 @@ def build(mkdocs_yml: Path) -> None:
mkdocs_build(load_config(str(mkdocs_yml))) mkdocs_build(load_config(str(mkdocs_yml)))
def serve(mkdocs_yml: Path) -> None: def serve(mkdocs_yml: Path) -> None:
""" """
Start an MkDocs development server with live reload. Serve the documentation site with live-reload using MkDocs.
The server watches documentation files and automatically reloads
the site when changes are detected.
Args: Args:
mkdocs_yml (Path): mkdocs_yml: Path to the mkdocs.yml configuration file.
Path to the `mkdocs.yml` configuration file.
Raises:
click.ClickException:
If the configuration file does not exist.
""" """
if not mkdocs_yml.exists(): if not mkdocs_yml.exists():
raise click.ClickException(f"mkdocs.yml not found: {mkdocs_yml}") raise click.ClickException(f"mkdocs.yml not found: {mkdocs_yml}")

7
docforge/cli/mkdocs_utils.pyi
View File

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

31
docforge/loaders/__init__.py
View File

@@ -1,28 +1,17 @@
""" """
# Summary # Loader Layer
Loader layer for doc-forge. The `docforge.loaders` package is responsible for discovering Python source files
and extracting their documentation using static analysis.
The `docforge.loaders` package is responsible for discovering Python modules ## Core Features
and extracting documentation data using static analysis.
--- - **Discovery**: Automatically find all modules and packages in a project
directory.
# Overview - **Introspection**: Uses `griffe` to parse docstrings, signatures, and
hierarchical relationships without executing the code.
This layer converts Python source code into an intermediate documentation - **Filtering**: Automatically excludes private members (prefixed with `_`) to
model used by doc-forge. It performs module discovery, introspection, and ensure clean public documentation.
initial filtering before the data is passed to the core documentation models.
Core capabilities include:
- **Module discovery** – Locate Python modules and packages within a project.
- **Static introspection** – Parse docstrings, signatures, and object
hierarchies using the `griffe` library without executing the code.
- **Public API filtering** – Exclude private members (names prefixed with
`_`) to produce clean public documentation structures.
---
""" """
from .griffe_loader import GriffeLoader, discover_module_paths from .griffe_loader import GriffeLoader, discover_module_paths

135
docforge/loaders/griffe_loader.py
View File

@@ -1,11 +1,6 @@
""" """
# Summary This module provides the GriffeLoader, which uses the 'griffe' library to
introspect Python source code and populate the doc-forge Project models.
Utilities for loading and introspecting Python modules using Griffe.
This module provides the `GriffeLoader` class and helper utilities used to
discover Python modules, introspect their structure, and convert the results
into doc-forge documentation models.
""" """
import logging import logging
@@ -30,32 +25,19 @@ def discover_module_paths(
project_root: Path | None = None, project_root: Path | None = None,
) -> List[str]: ) -> List[str]:
""" """
Discover Python modules within a package directory. Discover all Python modules under a package via filesystem traversal.
The function scans the filesystem for `.py` files inside the specified Rules:
package and converts them into dotted module import paths. - Directory with __init__.py is treated as a package.
- Any .py file is treated as a module.
Discovery rules: - All paths are converted to dotted module paths.
- Directories containing `__init__.py` are treated as packages.
- Each `.py` file is treated as a module.
- Results are returned as dotted import paths.
Args: Args:
module_name (str): module_name: The name of the package to discover.
Top-level package name to discover modules from. project_root: The root directory of the project. Defaults to current working directory.
project_root (Path, optional):
Root directory used to resolve module paths. If not provided, the
current working directory is used.
Returns: Returns:
List[str]: A sorted list of dotted module paths.
A sorted list of unique dotted module import paths.
Raises:
FileNotFoundError:
If the specified package directory does not exist.
""" """
if project_root is None: if project_root is None:
@@ -82,19 +64,12 @@ def discover_module_paths(
class GriffeLoader: class GriffeLoader:
""" """
Load Python modules using Griffe and convert them into doc-forge models. Loads Python modules and extracts documentation using the Griffe introspection engine.
This loader uses the Griffe introspection engine to analyze Python source
code and transform the extracted information into `Project`, `Module`,
and `DocObject` instances used by doc-forge.
""" """
def __init__(self) -> None: def __init__(self) -> None:
""" """
Initialize the Griffe-backed loader. Initialize the GriffeLoader.
Creates an internal Griffe loader instance with dedicated collections
for modules and source lines.
""" """
self._loader = _GriffeLoader( self._loader = _GriffeLoader(
modules_collection=ModulesCollection(), modules_collection=ModulesCollection(),
@@ -102,39 +77,21 @@ class GriffeLoader:
) )
def load_project( def load_project(
self, self,
module_paths: List[str], module_paths: List[str],
project_name: Optional[str] = None, project_name: Optional[str] = None,
skip_import_errors: bool = None, skip_import_errors: bool = None,
) -> Project: ) -> Project:
""" """
Load multiple modules and assemble them into a Project model. Load multiple modules and combine them into a single Project models.
Each module path is introspected and converted into a `Module`
instance. All modules are then aggregated into a single `Project`
object.
Args: Args:
module_paths (List[str]): module_paths: A list of dotted paths to the modules to load.
List of dotted module import paths to load. project_name: Optional name for the project. Defaults to the first module name.
skip_import_errors: If True, modules that fail to import will be skipped.
project_name (str, optional):
Optional override for the project name. Defaults to the top-level
name of the first module.
skip_import_errors (bool, optional):
If True, modules that fail to load will be skipped instead of raising an error.
Returns: Returns:
Project: A Project instance containing the loaded modules.
A populated `Project` instance containing the loaded modules.
Raises:
ValueError:
If no module paths are provided.
ImportError:
If a module fails to load and `skip_import_errors` is False.
""" """
if not module_paths: if not module_paths:
raise ValueError("At least one module path must be provided") raise ValueError("At least one module path must be provided")
@@ -159,18 +116,13 @@ class GriffeLoader:
def load_module(self, path: str) -> Module: def load_module(self, path: str) -> Module:
""" """
Load and convert a single Python module. Load a single module and convert its introspection data into the docforge models.
The module is introspected using Griffe and then transformed into
a doc-forge `Module` model.
Args: Args:
path (str): path: The dotted path of the module to load.
Dotted import path of the module.
Returns: Returns:
Module: A Module instance.
A populated `Module` instance.
""" """
self._loader.load(path) self._loader.load(path)
griffe_module = self._loader.modules_collection[path] griffe_module = self._loader.modules_collection[path]
@@ -183,18 +135,13 @@ class GriffeLoader:
def _convert_module(self, obj: Object) -> Module: def _convert_module(self, obj: Object) -> Module:
""" """
Convert a Griffe module object into a doc-forge Module. Convert a Griffe Object (module) into a docforge Module.
All public members of the module are recursively converted into
`DocObject` instances.
Args: Args:
obj (Object): obj: The Griffe Object representing the module.
Griffe object representing the module.
Returns: Returns:
Module: A populated Module instance.
A populated `Module` model.
""" """
module = Module( module = Module(
path=obj.path, path=obj.path,
@@ -211,19 +158,13 @@ class GriffeLoader:
def _convert_object(self, obj: Object) -> DocObject: def _convert_object(self, obj: Object) -> DocObject:
""" """
Convert a Griffe object into a doc-forge DocObject. Recursively convert a Griffe Object into a DocObject hierarchy.
The conversion preserves the object's metadata such as name,
kind, path, signature, and docstring. Child members are processed
recursively.
Args: Args:
obj (Object): obj: The Griffe Object to convert.
Griffe object representing a documented Python object.
Returns: Returns:
DocObject: A DocObject instance.
A `DocObject` instance representing the converted object.
""" """
kind = obj.kind.value kind = obj.kind.value
signature = self._safe_signature(obj) signature = self._safe_signature(obj)
@@ -252,15 +193,13 @@ class GriffeLoader:
def _safe_docstring(self, obj: Object) -> Optional[str]: def _safe_docstring(self, obj: Object) -> Optional[str]:
""" """
Safely extract a docstring from a Griffe object. Safely retrieve the docstring value from a Griffe object.
Args: Args:
obj (Object): obj: The Griffe Object to inspect.
Griffe object to inspect.
Returns: Returns:
Optional[str]: The raw docstring string, or None if missing or unresolvable.
The raw docstring text if available, otherwise `None`.
""" """
try: try:
return obj.docstring.value if obj.docstring else None return obj.docstring.value if obj.docstring else None
@@ -269,15 +208,13 @@ class GriffeLoader:
def _safe_signature(self, obj: Object) -> Optional[str]: def _safe_signature(self, obj: Object) -> Optional[str]:
""" """
Safely extract the signature of a Griffe object. Safely retrieve the signature string from a Griffe object.
Args: Args:
obj (Object): obj: The Griffe Object to inspect.
Griffe object to inspect.
Returns: Returns:
Optional[str]: The string representation of the signature, or None.
String representation of the object's signature if available, otherwise `None`.
""" """
try: try:
if hasattr(obj, "signature") and obj.signature: if hasattr(obj, "signature") and obj.signature:

34
docforge/models/__init__.py
View File

@@ -1,33 +1,17 @@
""" """
# Summary # Model Layer
Model layer for doc-forge. The `docforge.models` package provides the core data structures used to represent
Python source code in a documentation-focused hierarchy.
The `docforge.models` package defines the core data structures used to ## Key Components
represent Python source code as a structured documentation model.
--- - **Project**: The root container for all documented modules.
- **Module**: Represents a Python module or package, containing members.
- **DocObject**: A recursive structure for classes, functions, and attributes.
# Overview These classes are designed to be renderer-agnostic, allowing the same internal
representation to be transformed into various output formats (currently MkDocs).
The model layer forms the central intermediate representation used throughout
doc-forge. Python modules and objects discovered during introspection are
converted into a hierarchy of documentation models that can later be rendered
into different documentation formats.
Key components:
- **Project** – Root container representing an entire documented codebase.
- **Module** – Representation of a Python module or package containing
documented members.
- **DocObject** – Recursive structure representing Python objects such as
classes, functions, methods, and attributes.
These models are intentionally **renderer-agnostic**, allowing the same
documentation structure to be transformed into multiple output formats
(e.g., MkDocs, MCP, or other renderers).
---
""" """
from .project import Project from .project import Project

57
docforge/models/module.py
View File

@@ -1,12 +1,7 @@
""" """
# Summary This module defines the Module class, which represents a Python module or package
in the doc-forge documentation models. It acts as a container for top-level
Documentation model representing a Python module or package. documented objects.
This module defines the `Module` class used in the doc-forge documentation
model. A `Module` acts as a container for top-level documented objects
(classes, functions, variables, and other members) discovered during
introspection.
""" """
from typing import Dict, Iterable, Optional from typing import Dict, Iterable, Optional
@@ -16,21 +11,12 @@ from docforge.models.object import DocObject
class Module: class Module:
""" """
Representation of a documented Python module or package. Represents a documented Python module or package.
A `Module` stores metadata about the module itself and maintains a
collection of top-level documentation objects discovered during
introspection.
Attributes: Attributes:
path (str): path: Dotted import path of the module.
Dotted import path of the module. docstring: Module-level docstring content.
members: Dictionary mapping object names to their DocObject representations.
docstring (Optional[str]):
Module-level documentation string, if present.
members (Dict[str, DocObject]):
Mapping of object names to their corresponding `DocObject` representations.
""" """
def __init__( def __init__(
@@ -39,14 +25,11 @@ class Module:
docstring: Optional[str] = None, docstring: Optional[str] = None,
) -> None: ) -> None:
""" """
Initialize a Module instance. Initialize a new Module.
Args: Args:
path (str): path: The dotted path of the module.
Dotted import path identifying the module. docstring: The module's docstring, if any.
docstring (Optional[str]):
Module-level documentation text, if available.
""" """
self.path = path self.path = path
self.docstring = docstring self.docstring = docstring
@@ -57,35 +40,27 @@ class Module:
Add a documented object to the module. Add a documented object to the module.
Args: Args:
obj (DocObject): obj: The object to add.
Documentation object to register as a top-level member of the module.
""" """
self.members[obj.name] = obj self.members[obj.name] = obj
def get_object(self, name: str) -> DocObject: def get_object(self, name: str) -> DocObject:
""" """
Retrieve a documented object by name. Retrieve a member object by name.
Args: Args:
name (str): name: The name of the object.
Name of the object to retrieve.
Returns: Returns:
DocObject: The requested DocObject.
The corresponding `DocObject` instance.
Raises:
KeyError:
If no object with the given name exists.
""" """
return self.members[name] return self.members[name]
def get_all_objects(self) -> Iterable[DocObject]: def get_all_objects(self) -> Iterable[DocObject]:
""" """
Return all top-level documentation objects in the module. Get all top-level objects in the module.
Returns: Returns:
Iterable[DocObject]: An iterable of DocObject instances.
An iterable of `DocObject` instances representing the module's public members.
""" """
return self.members.values() return self.members.values()

93
docforge/models/object.py
View File

@@ -1,12 +1,7 @@
""" """
# Summary This module defines the DocObject class, the fundamental recursive unit of the
doc-forge documentation models. A DocObject represents a single Python entity
Documentation model representing individual Python objects. (class, function, method, or attribute) and its nested members.
This module defines the `DocObject` class, the fundamental recursive unit of
the doc-forge documentation model. Each `DocObject` represents a Python
entity such as a class, function, method, or attribute, and may contain nested
members that form a hierarchical documentation structure.
""" """
from typing import Dict, Iterable, Optional from typing import Dict, Iterable, Optional
@@ -14,30 +9,15 @@ from typing import Dict, Iterable, Optional
class DocObject: class DocObject:
""" """
Representation of a documented Python object. Represents a documented Python object (class, function, method, etc.).
A `DocObject` models a single Python entity discovered during
introspection. Objects may contain nested members, allowing the structure
of modules, classes, and other containers to be represented recursively.
Attributes: Attributes:
name (str): name: Local name of the object.
Local name of the object. kind: Type of object (e.g., 'class', 'function', 'attribute').
path: Full dotted import path to the object.
kind (str): signature: Callable signature, if applicable.
Type of object (for example `class`, `function`, `method`, or `attribute`). docstring: Raw docstring content extracted from the source.
members: Dictionary mapping member names to their DocObject representations.
path (str):
Fully qualified dotted path to the object.
signature (Optional[str]):
Callable signature if the object represents a callable.
docstring (Optional[str]):
Raw docstring text extracted from the source code.
members (Dict[str, DocObject]):
Mapping of member names to child `DocObject` instances.
""" """
def __init__( def __init__(
@@ -49,67 +29,48 @@ class DocObject:
docstring: Optional[str] = None, docstring: Optional[str] = None,
) -> None: ) -> None:
""" """
Initialize a DocObject instance. Initialize a new DocObject.
Args: Args:
name (str): name: The local name of the object.
Local name of the object. kind: The kind of object (e.g., 'class', 'function').
path: The full dotted path to the object.
kind (str): signature: The object's signature (for callable objects).
Object type identifier (for example `class` or `function`). docstring: The object's docstring, if any.
path (str):
Fully qualified dotted path of the object.
signature (Optional[str]):
Callable signature if applicable.
docstring (Optional[str]):
Documentation string associated with the object.
""" """
self.name = name self.name = name
self.kind = kind self.kind = kind
self.path = path self.path = path
self.signature = signature self.signature = signature
self.docstring = docstring self.docstring = docstring
self.members: Dict[str, "DocObject"] = {} self.members: Dict[str, 'DocObject'] = {}
def add_member(self, obj: "DocObject") -> None: def add_member(self, obj: 'DocObject') -> None:
""" """
Add a child documentation object. Add a child member to this object (e.g., a method to a class).
This is typically used when attaching methods to classes or
nested objects to their parent containers.
Args: Args:
obj: Documentation object to add as a member. obj: The child DocObject to add.
""" """
self.members[obj.name] = obj self.members[obj.name] = obj
def get_member(self, name: str) -> "DocObject": def get_member(self, name: str) -> 'DocObject':
""" """
Retrieve a member object by name. Retrieve a child member by name.
Args: Args:
name (str): name: The name of the member.
Name of the member to retrieve.
Returns: Returns:
DocObject: The requested DocObject.
The corresponding `DocObject` instance.
Raises:
KeyError:
If the member does not exist.
""" """
return self.members[name] return self.members[name]
def get_all_members(self) -> Iterable["DocObject"]: def get_all_members(self) -> Iterable['DocObject']:
""" """
Return all child members of the object. Get all members of this object.
Returns: Returns:
Iterable[DocObject]: An iterable of child DocObject instances.
An iterable of `DocObject` instances representing nested members.
""" """
return self.members.values() return self.members.values()

53
docforge/models/project.py
View File

@@ -1,11 +1,6 @@
""" """
# Summary This module defines the Project class, the top-level container for a documented
project. It aggregates multiple Module instances into a single named entity.
Documentation model representing a project.
This module defines the `Project` class, the top-level container used by
doc-forge to represent a documented codebase. A `Project` aggregates multiple
modules and provides access to them through a unified interface.
""" """
from typing import Dict, Iterable from typing import Dict, Iterable
@@ -15,37 +10,29 @@ from docforge.models.module import Module
class Project: class Project:
""" """
Representation of a documentation project. Represents a documentation project, serving as a container for modules.
A `Project` serves as the root container for all modules discovered during
introspection. Each module is stored by its dotted import path.
Attributes: Attributes:
name (str): name: Name of the project.
Name of the project. modules: Dictionary mapping module paths to Module instances.
modules (Dict[str, Module]):
Mapping of module paths to `Module` instances.
""" """
def __init__(self, name: str) -> None: def __init__(self, name: str) -> None:
""" """
Initialize a Project instance. Initialize a new Project.
Args: Args:
name (str): name: The name of the project.
Name used to identify the documentation project.
""" """
self.name = name self.name = name
self.modules: Dict[str, Module] = {} self.modules: Dict[str, Module] = {}
def add_module(self, module: Module) -> None: def add_module(self, module: Module) -> None:
""" """
Register a module in the project. Add a module to the project.
Args: Args:
module (Module): module: The module to add.
Module instance to add to the project.
""" """
self.modules[module.path] = module self.modules[module.path] = module
@@ -54,35 +41,27 @@ class Project:
Retrieve a module by its dotted path. Retrieve a module by its dotted path.
Args: Args:
path (str): path: The dotted path of the module (e.g., 'pkg.mod').
Fully qualified dotted module path (for example `pkg.module`).
Returns: Returns:
Module: The requested Module.
The corresponding `Module` instance.
Raises:
KeyError:
If the module does not exist in the project.
""" """
return self.modules[path] return self.modules[path]
def get_all_modules(self) -> Iterable[Module]: def get_all_modules(self) -> Iterable[Module]:
""" """
Return all modules contained in the project. Get all modules in the project.
Returns: Returns:
Iterable[Module]: An iterable of Module objects.
An iterable of `Module` instances.
""" """
return self.modules.values() return self.modules.values()
def get_module_list(self) -> list[str]: def get_module_list(self) -> list[str]:
""" """
Return the list of module import paths. Get the list of all module dotted paths.
Returns: Returns:
list[str]: A list of module paths.
A list containing the dotted paths of all modules in the project.
""" """
return list(self.modules.keys()) return list(self.modules.keys())

27
docforge/nav/__init__.py
View File

@@ -1,26 +1,17 @@
""" """
Navigation layer for doc-forge. # Navigation Layer
The ``docforge.nav`` package manages the relationship between the logical The `docforge.nav` package manages the mapping between the logical documentation
documentation structure defined by the user and the physical documentation structure and the physical files on disk.
files generated on disk.
--- ## Workflow
Workflow 1. **Spec Definition**: Users define navigation intent in `docforge.nav.yml`.
-------- 2. **Resolution**: `resolve_nav` matches patterns in the spec to generated `.md` files.
3. **Emission**: `MkDocsNavEmitter` produces the final YAML structure for `mkdocs.yml`.
1. **Specification** – Users define navigation intent in ``docforge.nav.yml``. This abstraction allows doc-forge to support complex grouping and ordering
2. **Resolution** – ``resolve_nav`` expands patterns and matches them against independently of the source code's physical layout.
generated Markdown files.
3. **Emission** – ``MkDocsNavEmitter`` converts the resolved structure into
the YAML navigation format required by ``mkdocs.yml``.
This layer separates documentation organization from the underlying source
code layout, enabling flexible grouping, ordering, and navigation structures
independent of module hierarchy.
---
""" """
from .spec import NavSpec, load_nav_spec from .spec import NavSpec, load_nav_spec

39
docforge/nav/mkdocs.py
View File

@@ -1,9 +1,7 @@
""" """
MkDocs navigation emitter. This module provides the MkDocsNavEmitter, which converts a ResolvedNav instance
into the specific YAML-ready list structure expected by the MkDocs 'nav'
This module provides the ``MkDocsNavEmitter`` class, which converts a configuration.
``ResolvedNav`` instance into the navigation structure required by the
MkDocs ``nav`` configuration.
""" """
from pathlib import Path from pathlib import Path
@@ -14,24 +12,19 @@ from docforge.nav.resolver import ResolvedNav
class MkDocsNavEmitter: class MkDocsNavEmitter:
""" """
Emit MkDocs navigation structures from resolved navigation data. Emitter responsible for transforming a ResolvedNav into an MkDocs-compatible
navigation structure.
The emitter transforms a ``ResolvedNav`` object into the YAML-compatible
list structure expected by the MkDocs ``nav`` configuration field.
""" """
def emit(self, nav: ResolvedNav) -> List[Dict[str, Any]]: def emit(self, nav: ResolvedNav) -> List[Dict[str, Any]]:
""" """
Generate a navigation structure for ``mkdocs.yml``. Generate a list of navigation entries for mkdocs.yml.
Args: Args:
nav: Resolved navigation data describing documentation groups nav: The resolved navigation data.
and their associated Markdown files.
Returns: Returns:
A list of dictionaries representing the MkDocs navigation layout. A list of dictionary mappings representing the MkDocs navigation.
Each dictionary maps a navigation label to a page or a list of
pages.
""" """
result: List[Dict[str, Any]] = [] result: List[Dict[str, Any]] = []
@@ -52,18 +45,16 @@ class MkDocsNavEmitter:
def _to_relative(self, path: Path, docs_root: Path | None) -> str: def _to_relative(self, path: Path, docs_root: Path | None) -> str:
""" """
Convert a filesystem path into a documentation-relative path. Convert a filesystem path to a path relative to the documentation root.
This handles both absolute and relative filesystem paths, ensuring the
This method normalizes paths so they can be used in MkDocs navigation. output is compatible with MkDocs navigation requirements.
It handles both absolute and relative filesystem paths and ensures the
resulting path is relative to the documentation root.
Args: Args:
path: Filesystem path to convert. path: The path to convert.
docs_root: Root directory of the documentation sources. docs_root: The root directory for documentation.
Returns: Returns:
POSIX-style path relative to the documentation root. A string representing the relative POSIX-style path.
""" """
if docs_root and path.is_absolute(): if docs_root and path.is_absolute():
try: try:
@@ -76,6 +67,6 @@ class MkDocsNavEmitter:
docs_root_str = docs_root.as_posix() docs_root_str = docs_root.as_posix()
if path_str.startswith(docs_root_str + "/"): if path_str.startswith(docs_root_str + "/"):
return path_str[len(docs_root_str) + 1:] return path_str[len(docs_root_str) + 1:]
# Fallback for other cases # Fallback for other cases
return path.as_posix().split("/docs/", 1)[-1] return path.as_posix().split("/docs/", 1)[-1]

60
docforge/nav/resolver.py
View File

@@ -1,8 +1,7 @@
""" """
Navigation resolution utilities. This module contains the logic for resolving a NavSpec against the physical
filesystem. It expands globs and validates that all referenced documents
This module resolves a ``NavSpec`` against the filesystem by expanding glob actually exist on disk.
patterns and validating that referenced documentation files exist.
""" """
from pathlib import Path from pathlib import Path
@@ -15,15 +14,12 @@ from docforge.nav.spec import NavSpec
class ResolvedNav: class ResolvedNav:
""" """
Resolved navigation structure. Represents a navigation structure where all patterns and paths have been
resolved against the actual filesystem contents.
A ``ResolvedNav`` represents navigation data after glob patterns have been
expanded and paths validated against the filesystem.
Attributes: Attributes:
home: Relative path to the documentation home page. home: Resolved relative path to the home page.
groups: Mapping of navigation group titles to lists of resolved groups: Mapping of group titles to lists of absolute or relative Path objects.
documentation file paths.
""" """
def __init__( def __init__(
@@ -36,9 +32,9 @@ class ResolvedNav:
Initialize a ResolvedNav instance. Initialize a ResolvedNav instance.
Args: Args:
home: Relative path to the home page within the documentation root. home: The relative path to the project home page.
groups: Mapping of group titles to resolved documentation file paths. groups: A mapping of group names to their resolved filesystem paths.
docs_root: Root directory of the documentation source files. docs_root: The root documentation directory.
""" """
self.home = home self.home = home
self.groups = groups self.groups = groups
@@ -46,20 +42,15 @@ class ResolvedNav:
def all_files(self) -> Iterable[Path]: def all_files(self) -> Iterable[Path]:
""" """
Iterate over all files referenced by the navigation structure. Get an iterable of all resolved files in the navigation structure.
Returns: Returns:
An iterable of ``Path`` objects representing documentation files. An iterable of Path objects.
Raises:
RuntimeError: If the home page is defined but the documentation
root is not available for resolution.
""" """
if self.home: if self.home:
if self._docs_root is None: if self._docs_root is None:
raise RuntimeError("docs_root is required to resolve home path") raise RuntimeError("docs_root is required to resolve home path")
yield self._docs_root / self.home yield self._docs_root / self.home
for paths in self.groups.values(): for paths in self.groups.values():
for p in paths: for p in paths:
yield p yield p
@@ -70,37 +61,34 @@ def resolve_nav(
docs_root: Path, docs_root: Path,
) -> ResolvedNav: ) -> ResolvedNav:
""" """
Resolve a navigation specification against the filesystem. Create a ResolvedNav by processing a NavSpec against the filesystem.
This expands globs and validates the existence of referenced files.
The function expands glob patterns defined in a ``NavSpec`` and verifies
that referenced documentation files exist within the documentation root.
Args: Args:
spec: Navigation specification describing documentation layout. spec: The navigation specification to resolve.
docs_root: Root directory containing documentation Markdown files. docs_root: The root directory for documentation files.
Returns: Returns:
A ``ResolvedNav`` instance containing validated navigation paths. A ResolvedNav instance.
Raises: Raises:
FileNotFoundError: If the documentation root does not exist or a FileNotFoundError: If a pattern doesn't match any files or the docs_root doesn't exist.
navigation pattern does not match any files.
""" """
if not docs_root.exists(): if not docs_root.exists():
raise FileNotFoundError(docs_root) raise FileNotFoundError(docs_root)
def resolve_pattern(pattern: str) -> List[Path]: def resolve_pattern(pattern: str) -> List[Path]:
""" """
Resolve a glob pattern relative to the documentation root. Resolve a single glob pattern relative to the docs_root.
Args: Args:
pattern: Glob pattern used to match documentation files. pattern: The glob pattern to resolve.
Returns: Returns:
A sorted list of matching ``Path`` objects. A sorted list of matching Path objects.
Raises: Raises:
FileNotFoundError: If the pattern does not match any files. FileNotFoundError: If the pattern doesn't match any files.
""" """
full = docs_root / pattern full = docs_root / pattern
matches = sorted( matches = sorted(
@@ -112,7 +100,7 @@ def resolve_nav(
return matches return matches
# Resolve home page # Resolve home
home: str | None = None home: str | None = None
if spec.home: if spec.home:
home_path = docs_root / spec.home home_path = docs_root / spec.home
@@ -120,7 +108,7 @@ def resolve_nav(
raise FileNotFoundError(spec.home) raise FileNotFoundError(spec.home)
home = spec.home home = spec.home
# Resolve navigation groups # Resolve groups
resolved_groups: Dict[str, List[Path]] = {} resolved_groups: Dict[str, List[Path]] = {}
for group, patterns in spec.groups.items(): for group, patterns in spec.groups.items():

57
docforge/nav/spec.py
View File

@@ -1,9 +1,7 @@
""" """
Navigation specification model. This module defines the NavSpec class, which represents the user's intent for
documentation navigation as defined in a YAML specification (usually
This module defines the ``NavSpec`` class, which represents the navigation docforge.nav.yml).
structure defined by the user in the doc-forge navigation specification
(typically ``docforge.nav.yml``).
""" """
from pathlib import Path from pathlib import Path
@@ -14,16 +12,11 @@ import yaml
class NavSpec: class NavSpec:
""" """
Parsed representation of a navigation specification. Parsed representation of the docforge navigation specification file.
A ``NavSpec`` describes the intended documentation navigation layout before
it is resolved against the filesystem.
Attributes: Attributes:
home: Relative path to the documentation home page (for example home: Path to the home document (e.g., 'index.md').
``index.md``). groups: Mapping of group titles to lists of path patterns/globs.
groups: Mapping of navigation group titles to lists of file patterns
or glob expressions.
""" """
def __init__( def __init__(
@@ -32,12 +25,11 @@ class NavSpec:
groups: Dict[str, List[str]], groups: Dict[str, List[str]],
) -> None: ) -> None:
""" """
Initialize a NavSpec instance. Initialize a NavSpec.
Args: Args:
home: Relative path to the home document. home: The path to the home document.
groups: Mapping of group names to lists of path patterns groups: A mapping of group names to lists of path patterns (globs).
(glob expressions).
""" """
self.home = home self.home = home
self.groups = groups self.groups = groups
@@ -45,18 +37,17 @@ class NavSpec:
@classmethod @classmethod
def load(cls, path: Path) -> "NavSpec": def load(cls, path: Path) -> "NavSpec":
""" """
Load a navigation specification from a YAML file. Load a NavSpec from a YAML file.
Args: Args:
path: Filesystem path to the navigation specification file. path: The filesystem path to the YAML file.
Returns: Returns:
A ``NavSpec`` instance representing the parsed configuration. A NavSpec instance.
Raises: Raises:
FileNotFoundError: If the specified file does not exist. FileNotFoundError: If the path does not exist.
ValueError: If the file contents are not a valid navigation ValueError: If the file content is not a valid NavSpec mapping.
specification.
""" """
if not path.exists(): if not path.exists():
raise FileNotFoundError(path) raise FileNotFoundError(path)
@@ -87,45 +78,33 @@ class NavSpec:
def all_patterns(self) -> List[str]: def all_patterns(self) -> List[str]:
""" """
Return all path patterns referenced by the specification. Get all path patterns referenced in the specification.
Returns: Returns:
A list containing the home document (if defined) and all A list of all patterns (home plus all groups).
group pattern entries.
""" """
patterns: List[str] = [] patterns: List[str] = []
if self.home: if self.home:
patterns.append(self.home) patterns.append(self.home)
for items in self.groups.values(): for items in self.groups.values():
patterns.extend(items) patterns.extend(items)
return patterns return patterns
def load_nav_spec(path: Path) -> NavSpec: def load_nav_spec(path: Path) -> NavSpec:
""" """
Load a navigation specification file. Utility function to load a NavSpec from a file.
This helper function reads a YAML navigation file and constructs a
corresponding ``NavSpec`` instance.
Args: Args:
path: Path to the navigation specification file. path: Path to the navigation specification file.
Returns: Returns:
A ``NavSpec`` instance representing the parsed specification. A loaded NavSpec instance.
Raises:
FileNotFoundError: If the specification file does not exist.
ValueError: If the YAML structure is invalid.
""" """
if not path.exists(): if not path.exists():
raise FileNotFoundError(path) raise FileNotFoundError(path)
data = yaml.safe_load(path.read_text(encoding="utf-8")) data = yaml.safe_load(path.read_text(encoding="utf-8"))
if not isinstance(data, dict): if not isinstance(data, dict):
raise ValueError("Nav spec must be a YAML mapping") raise ValueError("Nav spec must be a YAML mapping")

36
docforge/renderers/__init__.py
View File

@@ -1,34 +1,20 @@
""" """
# Summary # Renderers Layer
Renderers layer for doc-forge. The `docforge.renderers` package handles the transformation of the internal
documentation models into physical files formatted for specific documentation
engines.
The `docforge.renderers` package transforms the internal documentation ## Current Implementations
models into files formatted for specific documentation systems.
--- - **MkDocsRenderer**: Generates Markdown files utilizing the `mkdocstrings`
syntax. It automatically handles package/module hierarchy and generates
`index.md` files for packages.
# Overview ## Extending
Renderers consume the doc-forge project model and generate output suitable To add a new renderer, implement the `DocRenderer` protocol defined in
for documentation tools or machine interfaces. `docforge.renderers.base`.
Current implementations:
- **MkDocsRenderer** – Produces Markdown files compatible with MkDocs and
the `mkdocstrings` plugin. It automatically handles package hierarchy
and generates `index.md` files for packages.
- **MCPRenderer** – Emits structured JSON resources designed for consumption
by Model Context Protocol (MCP) clients.
---
# Extending
New renderers can be added by implementing the `DocRenderer` protocol
defined in `docforge.renderers.base`.
---
""" """
from .mkdocs_renderer import MkDocsRenderer from .mkdocs_renderer import MkDocsRenderer

44
docforge/renderers/base.py
View File

@@ -1,11 +1,7 @@
""" """
# Summary This module defines the base interfaces and configuration containers for
doc-forge renderers. All renderer implementations should adhere to the
Renderer base interfaces and configuration models. DocRenderer protocol.
This module defines the base protocol and configuration container used by
doc-forge renderers. Concrete renderer implementations should implement the
`DocRenderer` protocol.
""" """
from pathlib import Path from pathlib import Path
@@ -18,28 +14,12 @@ class RendererConfig:
""" """
Configuration container for documentation renderers. Configuration container for documentation renderers.
A `RendererConfig` instance groups together the project model and the Args:
output directory used during rendering. out_dir: The directory where documentation files should be written.
project: The introspected project models to be rendered.
Attributes:
out_dir (Path):
Directory where generated documentation files will be written.
project (Project):
Documentation project model to be rendered.
""" """
def __init__(self, out_dir: Path, project: Project) -> None: def __init__(self, out_dir: Path, project: Project) -> None:
"""
Initialize a RendererConfig instance.
Args:
out_dir (Path):
Target directory where documentation files should be written.
project (Project):
Introspected project model to render.
"""
self.out_dir = out_dir self.out_dir = out_dir
self.project = project self.project = project
@@ -47,9 +27,6 @@ class RendererConfig:
class DocRenderer(Protocol): class DocRenderer(Protocol):
""" """
Protocol defining the interface for documentation renderers. Protocol defining the interface for documentation renderers.
Implementations of this protocol are responsible for transforming a
`Project` model into renderer-specific documentation sources.
""" """
name: str name: str
@@ -60,13 +37,10 @@ class DocRenderer(Protocol):
out_dir: Path, out_dir: Path,
) -> None: ) -> None:
""" """
Generate renderer-specific documentation sources. Generate renderer-specific source files for the given project.
Args: Args:
project (Project): project: The project models containing modules and objects.
Project model containing modules and documentation objects. out_dir: Target directory for the generated files.
out_dir (Path):
Directory where generated documentation sources should be written.
""" """
... ...

63
docforge/renderers/mcp_renderer.py
View File

@@ -1,12 +1,3 @@
"""
# Summary
MCP renderer implementation.
This module defines the `MCPRenderer` class, which generates documentation
resources compatible with the Model Context Protocol (MCP).
"""
import json import json
from pathlib import Path from pathlib import Path
from typing import Dict, List from typing import Dict, List
@@ -16,28 +7,18 @@ from docforge.models import Project, Module, DocObject
class MCPRenderer: class MCPRenderer:
""" """
Renderer that generates MCP-compatible documentation resources. Renderer that emits MCP-native JSON resources from docforge models.
This renderer converts doc-forge project models into structured JSON
resources suitable for consumption by systems implementing the Model
Context Protocol (MCP).
""" """
name = "mcp" name = "mcp"
def generate_sources(self, project: Project, out_dir: Path) -> None: def generate_sources(self, project: Project, out_dir: Path) -> None:
""" """
Generate MCP documentation resources for a project. Generate MCP-compatible JSON resources and navigation for the project.
The renderer serializes each module into a JSON resource and produces
supporting metadata files such as `nav.json` and `index.json`.
Args: Args:
project (Project): project: The project model to render.
Documentation project model to render. out_dir: Target directory for the generated JSON files.
out_dir (Path):
Directory where MCP resources will be written.
""" """
modules_dir = out_dir / "modules" modules_dir = out_dir / "modules"
modules_dir.mkdir(parents=True, exist_ok=True) modules_dir.mkdir(parents=True, exist_ok=True)
@@ -73,14 +54,11 @@ class MCPRenderer:
def _write_module(self, module: Module, modules_dir: Path) -> None: def _write_module(self, module: Module, modules_dir: Path) -> None:
""" """
Serialize a module into an MCP resource file. Serialize a module into an MCP JSON resource on disk.
Args: Args:
module (Module): module: The module instance to serialize.
Module instance to serialize. modules_dir: The directory where the module JSON file should be written.
modules_dir (Path):
Directory where module JSON files are stored.
""" """
payload = { payload = {
"module": module.path, "module": module.path,
@@ -93,15 +71,13 @@ class MCPRenderer:
def _render_module(self, module: Module) -> Dict: def _render_module(self, module: Module) -> Dict:
""" """
Convert a Module model into MCP-compatible structured data. Render a Module into MCP-friendly structured data.
Args: Args:
module (Module): module: The module instance to render.
Module instance to convert.
Returns: Returns:
Dict: A dictionary following the MCP documentation resource schema.
Dictionary representing the module and its documented objects.
""" """
data: Dict = { data: Dict = {
"path": module.path, "path": module.path,
@@ -116,15 +92,13 @@ class MCPRenderer:
def _render_object(self, obj: DocObject) -> Dict: def _render_object(self, obj: DocObject) -> Dict:
""" """
Recursively convert a DocObject into structured MCP data. Recursively render a DocObject into structured MCP data.
Args: Args:
obj (DocObject): obj: The documented object (class, func, etc.) to render.
Documentation object to convert.
Returns: Returns:
Dict: A dictionary representing the object and its members.
Dictionary describing the object and any nested members.
""" """
data: Dict = { data: Dict = {
"name": obj.name, "name": obj.name,
@@ -145,15 +119,4 @@ class MCPRenderer:
@staticmethod @staticmethod
def _json(data: Dict) -> str: def _json(data: Dict) -> str:
"""
Serialize data to formatted JSON.
Args:
data (Dict):
Dictionary to serialize.
Returns:
str:
JSON string formatted with indentation and UTF-8 compatibility.
"""
return json.dumps(data, indent=2, ensure_ascii=False) return json.dumps(data, indent=2, ensure_ascii=False)

274
docforge/renderers/mkdocs_renderer.py
View File

@@ -1,305 +1,91 @@
""" """
# Summary This module implements the MkDocsRenderer, which generates Markdown source files
compatible with the MkDocs 'material' theme and 'mkdocstrings' extension.
MkDocs renderer implementation.
This module defines the `MkDocsRenderer` class, which generates Markdown
documentation sources compatible with MkDocs Material and the mkdocstrings
plugin.
The renderer ensures a consistent documentation structure by:
- Creating a root `index.md` if one does not exist
- Generating package index pages automatically
- Linking child modules within parent package pages
- Optionally generating `README.md` from the root package docstring
""" """
from pathlib import Path from pathlib import Path
from docforge.models import Project, Module
from docforge.models import Project
class MkDocsRenderer: class MkDocsRenderer:
""" """
Renderer that produces Markdown documentation for MkDocs. Renderer that generates Markdown source files formatted for the MkDocs
'mkdocstrings' plugin.
Generated pages use mkdocstrings directives to reference Python modules,
allowing MkDocs to render API documentation dynamically.
""" """
name = "mkdocs" 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:
""" """
Generate Markdown documentation files for a project. Produce a set of Markdown files in the output directory based on the
provided Project models.
This method renders a documentation structure from the provided
project model and writes the resulting Markdown files to the
specified output directory.
Args: Args:
project (Project): project: The project models to render.
Project model containing modules to document. out_dir: Target directory for documentation files.
out_dir (Path):
Directory where generated Markdown files will be written.
module_is_source (bool, optional):
If True, treat the specified module as the documentation root
rather than nesting it inside a folder.
""" """
out_dir.mkdir(parents=True, exist_ok=True)
self._ensure_root_index(project, out_dir)
modules = list(project.get_all_modules()) modules = list(project.get_all_modules())
paths = {m.path for m in modules} paths = {m.path for m in modules}
# Detect packages (modules with children) # Package detection (level-agnostic)
packages = { packages = {
p for p in paths p for p in paths
if any(other.startswith(p + ".") for other in paths) if any(other.startswith(p + ".") for other in paths)
} }
for module in modules: for module in modules:
self._write_module( self._write_module(module, packages, out_dir)
module,
packages,
out_dir,
module_is_source,
)
def generate_readme(
self,
project: Project,
docs_dir: Path,
module_is_source: bool | None = None,
) -> None:
"""
Generate a `README.md` file from the root module docstring.
Behavior:
- If `module_is_source` is True, `README.md` is written to the project
root directory.
- If False, README generation is currently not implemented.
Args:
project (Project):
Project model containing documentation metadata.
docs_dir (Path):
Directory containing generated documentation sources.
module_is_source (bool, optional):
Whether the module is treated as the project source root.
"""
if not module_is_source:
# Future: support README generation per module
return
readme_path = docs_dir.parent / "README.md"
root_module = None
for module in project.get_all_modules():
if module.path == project.name:
root_module = module
break
if root_module is None:
return
doc = ""
if root_module.docstring:
doc = getattr(
root_module.docstring,
"value",
str(root_module.docstring),
)
content = (
f"# {project.name}\n\n"
f"{doc.strip()}\n"
)
if not readme_path.exists() or readme_path.read_text(encoding="utf-8") != content:
readme_path.write_text(
content,
encoding="utf-8",
)
# ------------------------- # -------------------------
# Internal helpers # Internal helpers
# ------------------------- # -------------------------
def _write_module(self, module, packages: set[str], out_dir: Path) -> None:
def _find_root_module(self, project: Project) -> Module | None:
""" """
Locate the root module corresponding to the project name. Write a single module's documentation file. Packages are written as
'index.md' inside their respective directories.
Args: Args:
project (Project): module: The module to write.
Project model to inspect. packages: A set of module paths that are identified as packages.
out_dir: The base output directory.
Returns:
Optional[Module]:
The root `Module` if found, otherwise `None`.
""" """
for module in project.get_all_modules():
if module.path == project.name:
return module
return None
def _write_module(
self,
module: Module,
packages: set[str],
out_dir: Path,
module_is_source: bool | None = None,
) -> None:
"""
Write documentation for a single module.
Package modules are rendered as `index.md` files inside their
corresponding directories, while leaf modules are written as
standalone Markdown pages.
Args:
module (Module):
Module to render.
packages (set[str]):
Set of module paths identified as packages.
out_dir (Path):
Base directory for generated documentation files.
module_is_source (bool, optional):
Whether the module acts as the documentation root directory.
"""
parts = module.path.split(".") 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: if module.path in packages:
# package → index.md
dir_path = out_dir.joinpath(*parts) dir_path = out_dir.joinpath(*parts)
dir_path.mkdir(parents=True, exist_ok=True) dir_path.mkdir(parents=True, exist_ok=True)
md_path = dir_path / "index.md" md_path = dir_path / "index.md"
link_target = f"{parts[-1]}/" if parts else None title = parts[-1].replace("_", " ").title()
else: else:
# leaf module → <name>.md
dir_path = out_dir.joinpath(*parts[:-1]) dir_path = out_dir.joinpath(*parts[:-1])
dir_path.mkdir(parents=True, exist_ok=True) dir_path.mkdir(parents=True, exist_ok=True)
md_path = dir_path / f"{parts[-1]}.md" md_path = dir_path / f"{parts[-1]}.md"
link_target = f"{parts[-1]}.md" if parts else None title = parts[-1].replace("_", " ").title()
title = parts[-1].replace("_", " ").title() if parts else module_name
content = self._render_markdown(title, module.path) content = self._render_markdown(title, module.path)
if not md_path.exists() or md_path.read_text(encoding="utf-8") != content: if md_path.exists() and md_path.read_text(encoding="utf-8") == content:
md_path.write_text(content, encoding="utf-8") return
if not module_is_source: md_path.write_text(content, encoding="utf-8")
self._ensure_parent_index(parts, out_dir, link_target, title)
def _render_markdown(self, title: str, module_path: str) -> str: def _render_markdown(self, title: str, module_path: str) -> str:
""" """
Generate Markdown content for a module documentation page. Generate the Markdown content for a module file.
Args: Args:
title (str): title: The display title for the page.
Page title displayed in the documentation. module_path: The dotted path of the module to document.
module_path (str):
Dotted import path of the module.
Returns: Returns:
str: A string containing the Markdown source.
Markdown source containing a mkdocstrings directive.
""" """
return ( return (
f"# {title}\n\n" f"# {title}\n\n"
f"::: {module_path}\n" f"::: {module_path}\n"
) )
def _ensure_root_index(
self,
project: Project,
out_dir: Path,
) -> None:
"""
Ensure that the root `index.md` page exists.
Args:
project (Project):
Project model used for the page title.
out_dir (Path):
Documentation output directory.
"""
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:
"""
Ensure that parent package index files exist and contain links to
child modules.
Args:
parts (list[str]):
Module path components.
out_dir (Path):
Documentation output directory.
link_target (str):
Link target used in the parent index.
title (str):
Display title for the link.
"""
if len(parts) == 1:
parent_index = out_dir / "index.md"
else:
parent_dir = out_dir.joinpath(*parts[:-1])
parent_dir.mkdir(parents=True, exist_ok=True)
parent_index = parent_dir / "index.md"
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")
link = f"- [{title}]({link_target})\n"
if link not in content:
parent_index.write_text(content + link, encoding="utf-8")

25
docforge/renderers/mkdocs_renderer.pyi
View File

@@ -1,34 +1,17 @@
from pathlib import Path from pathlib import Path
from typing import Set
from docforge.models import Project, Module from docforge.models import Project, Module
class MkDocsRenderer: class MkDocsRenderer:
name: str name: str
def generate_sources( def generate_sources(self, project: Project, out_dir: Path) -> None: ...
self,
project: Project,
out_dir: Path,
module_is_source: bool | None = None,
) -> None: ...
def generate_readme(
self,
project: Project,
docs_dir: Path,
module_is_source: bool | None = None,
) -> None:
def _write_module( def _write_module(
self, self,
module: Module, module: Module,
packages: set[str], packages: Set[str],
out_dir: Path, out_dir: Path,
module_is_source: bool | None = None,
) -> None: ... ) -> None: ...
def _render_markdown(self, title: str, module_path: str) -> str: ... 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: ...

14
docforge/servers/__init__.py
View File

@@ -1,17 +1,5 @@
"""
# Summary
Server layer for doc-forge.
This module exposes server implementations used to provide live access
to generated documentation resources. Currently, it includes the MCP
documentation server.
---
"""
from .mcp_server import MCPServer from .mcp_server import MCPServer
__all__ = [ __all__ = [
"MCPServer", "MCPServer",
] ]

65
docforge/servers/mcp_server.py
View File

@@ -1,12 +1,3 @@
"""
# Summary
MCP server implementation.
This module defines the `MCPServer` class, which serves pre-generated
documentation bundles through the Model Context Protocol (MCP).
"""
from __future__ import annotations from __future__ import annotations
import json import json
@@ -18,23 +9,16 @@ from mcp.server.fastmcp import FastMCP
class MCPServer: class MCPServer:
""" """
MCP server for serving a pre-generated documentation bundle. MCP server for serving a pre-built MCP documentation bundle.
The server exposes documentation resources and diagnostic tools through
MCP endpoints backed by JSON files generated by the MCP renderer.
""" """
def __init__(self, mcp_root: Path, name: str) -> None: def __init__(self, mcp_root: Path, name: str) -> None:
""" """
Initialize the MCP server. Initialize the MCPServer.
Args: Args:
mcp_root (Path): mcp_root: Path to the directory containing pre-built MCP JSON resources.
Directory containing the generated MCP documentation bundle name: Name of the MCP server.
(for example `index.json`, `nav.json`, and `modules/`).
name (str):
Identifier used for the MCP server instance.
""" """
self.mcp_root = mcp_root self.mcp_root = mcp_root
self.app = FastMCP(name) self.app = FastMCP(name)
@@ -48,26 +32,19 @@ class MCPServer:
def _read_json(self, path: Path) -> Any: def _read_json(self, path: Path) -> Any:
""" """
Load and parse a JSON file. Read and parse a JSON file, returning diagnostic errors if missing.
If the file does not exist, a structured error response is returned
instead of raising an exception.
Args: Args:
path (Path): path: Path to the JSON file.
Path to the JSON file to read.
Returns: Returns:
Any: The parsed JSON data or an error dictionary.
Parsed JSON data if the file exists, otherwise an error dictionary
describing the missing resource.
""" """
if not path.exists(): if not path.exists():
return { return {
"error": "not_found", "error": "not_found",
"path": str(path), "path": str(path),
} }
return json.loads(path.read_text(encoding="utf-8")) return json.loads(path.read_text(encoding="utf-8"))
# ------------------------------------------------------------------ # ------------------------------------------------------------------
@@ -76,16 +53,8 @@ class MCPServer:
def _register_resources(self) -> None: def _register_resources(self) -> None:
""" """
Register MCP resource endpoints. Register MCP resources for index, nav, and individual modules.
The server exposes documentation resources through the following
endpoints:
- `docs://index` – Project metadata
- `docs://nav` – Navigation structure
- `docs://modules/{module}` – Individual module documentation
""" """
@self.app.resource("docs://index") @self.app.resource("docs://index")
def index(): def index():
return self._read_json(self.mcp_root / "index.json") return self._read_json(self.mcp_root / "index.json")
@@ -101,36 +70,26 @@ class MCPServer:
) )
# ------------------------------------------------------------------ # ------------------------------------------------------------------
# MCP tools # MCP tools (optional / diagnostic)
# ------------------------------------------------------------------ # ------------------------------------------------------------------
def _register_tools(self) -> None: def _register_tools(self) -> None:
""" """
Register optional MCP diagnostic tools. Register high-level MCP tools for diagnostics.
These tools provide lightweight endpoints useful for verifying that
the MCP server is operational.
""" """
@self.app.tool() @self.app.tool()
def ping() -> str: def ping() -> str:
"""Return a simple health check response."""
return "pong" return "pong"
# ------------------------------------------------------------------ # ------------------------------------------------------------------
# Server lifecycle # Server lifecycle
# ------------------------------------------------------------------ # ------------------------------------------------------------------
def run( def run(self, transport: Literal["stdio", "sse", "streamable-http"] = "streamable-http") -> None:
self,
transport: Literal["stdio", "sse", "streamable-http"] = "streamable-http",
) -> None:
""" """
Start the MCP server. Start the MCP server.
Args: Args:
transport (Literal["stdio", "sse", "streamable-http"]): transport: MCP transport (default: streamable-http)
Transport mechanism used by the MCP server. Supported options
include `stdio`, `sse`, and `streamable-http`.
""" """
self.app.run(transport=transport) self.app.run(transport=transport)

47
docforge/templates/mkdocs.sample.yml
View File

@@ -4,30 +4,16 @@ theme:
- scheme: slate - scheme: slate
primary: deep purple primary: deep purple
accent: cyan accent: cyan
font: font:
text: Inter text: Inter
code: JetBrains Mono code: JetBrains Mono
features: features:
# Navigation - navigation.tabs
- navigation.sections
- navigation.expand - navigation.expand
- navigation.top - navigation.top
- navigation.instant - navigation.instant
- navigation.tracking
- navigation.indexes
# Content
- content.code.copy - content.code.copy
- content.code.annotate - content.code.annotate
- content.tabs.link
- content.action.edit
# Search UX
- search.highlight
- search.share
- search.suggest
plugins: plugins:
- search - search
@@ -45,34 +31,3 @@ plugins:
annotations_path: brief annotations_path: brief
show_root_heading: true show_root_heading: true
group_by_category: true group_by_category: true
show_category_heading: true
show_object_full_path: false
show_symbol_type_heading: true
markdown_extensions:
- pymdownx.superfences
- pymdownx.inlinehilite
- pymdownx.snippets
- admonition
- pymdownx.details
- pymdownx.superfences
- pymdownx.highlight:
linenums: true
anchor_linenums: true
line_spans: __span
pygments_lang_class: true
- pymdownx.tabbed:
alternate_style: true
- pymdownx.tasklist:
custom_checkbox: true
- tables
- footnotes
- pymdownx.caret
- pymdownx.tilde
- pymdownx.mark

0
docs/cli/commands.md → docs/docforge/cli/commands.md
View File

0
docs/cli/index.md → docs/docforge/cli/index.md
View File

0
docs/cli/main.md → docs/docforge/cli/main.md
View File

0
docs/cli/mcp_utils.md → docs/docforge/cli/mcp_utils.md
View File

0
docs/cli/mkdocs_utils.md → docs/docforge/cli/mkdocs_utils.md
View File

2
docs/index.md → docs/docforge/index.md
View File

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

0
docs/loaders/griffe_loader.md → docs/docforge/loaders/griffe_loader.md
View File

0
docs/loaders/index.md → docs/docforge/loaders/index.md
View File

0
docs/models/index.md → docs/docforge/models/index.md
View File

0
docs/models/module.md → docs/docforge/models/module.md
View File

0
docs/models/object.md → docs/docforge/models/object.md
View File

0
docs/models/project.md → docs/docforge/models/project.md
View File

0
docs/nav/index.md → docs/docforge/nav/index.md
View File

0
docs/nav/mkdocs.md → docs/docforge/nav/mkdocs.md
View File

0
docs/nav/resolver.md → docs/docforge/nav/resolver.md
View File

0
docs/nav/spec.md → docs/docforge/nav/spec.md
View File

0
docs/renderers/base.md → docs/docforge/renderers/base.md
View File

0
docs/renderers/index.md → docs/docforge/renderers/index.md
View File

0
docs/renderers/mcp_renderer.md → docs/docforge/renderers/mcp_renderer.md
View File

0
docs/renderers/mkdocs_renderer.md → docs/docforge/renderers/mkdocs_renderer.md
View File

0
docs/servers/index.md → docs/docforge/servers/index.md
View File

0
docs/servers/mcp_server.md → docs/docforge/servers/mcp_server.md
View File

79
mcp_docs/modules/docforge.cli.commands.json
View File

@@ -2,7 +2,7 @@
"module": "docforge.cli.commands", "module": "docforge.cli.commands",
"content": { "content": {
"path": "docforge.cli.commands", "path": "docforge.cli.commands",
"docstring": "# Summary\n\nCommand definitions for the doc-forge CLI.\n\nProvides the CLI structure using Click, including build, serve, and tree commands.", "docstring": null,
"objects": { "objects": {
"click": { "click": {
"name": "click", "name": "click",
@@ -37,21 +37,21 @@
"kind": "class", "kind": "class",
"path": "docforge.cli.commands.GriffeLoader", "path": "docforge.cli.commands.GriffeLoader",
"signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.loaders.GriffeLoader')>", "signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.loaders.GriffeLoader')>",
"docstring": "Load Python modules using Griffe and convert them into doc-forge models.\n\nThis loader uses the Griffe introspection engine to analyze Python source\ncode and transform the extracted information into `Project`, `Module`,\nand `DocObject` instances used by doc-forge.", "docstring": "Loads Python modules and extracts documentation using the Griffe introspection engine.",
"members": { "members": {
"load_project": { "load_project": {
"name": "load_project", "name": "load_project",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.GriffeLoader.load_project", "path": "docforge.cli.commands.GriffeLoader.load_project",
"signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>", "signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>",
"docstring": "Load multiple modules and assemble them into a Project model.\n\nEach module path is introspected and converted into a `Module`\ninstance. All modules are then aggregated into a single `Project`\nobject.\n\nArgs:\n module_paths (List[str]):\n List of dotted module import paths to load.\n\n project_name (str, optional):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool, optional):\n If True, modules that fail to load will be skipped instead of raising an error.\n\nReturns:\n Project:\n A populated `Project` instance containing the loaded modules.\n\nRaises:\n ValueError:\n If no module paths are provided.\n\n ImportError:\n If a module fails to load and `skip_import_errors` is False." "docstring": "Load multiple modules and combine them into a single Project models.\n\nArgs:\n module_paths: A list of dotted paths to the modules to load.\n project_name: Optional name for the project. Defaults to the first module name.\n skip_import_errors: If True, modules that fail to import will be skipped.\n\nReturns:\n A Project instance containing the loaded modules."
}, },
"load_module": { "load_module": {
"name": "load_module", "name": "load_module",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.GriffeLoader.load_module", "path": "docforge.cli.commands.GriffeLoader.load_module",
"signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>", "signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>",
"docstring": "Load and convert a single Python module.\n\nThe module is introspected using Griffe and then transformed into\na doc-forge `Module` model.\n\nArgs:\n path (str):\n Dotted import path of the module.\n\nReturns:\n Module:\n A populated `Module` instance." "docstring": "Load a single module and convert its introspection data into the docforge models.\n\nArgs:\n path: The dotted path of the module to load.\n\nReturns:\n A Module instance."
} }
} }
}, },
@@ -60,7 +60,7 @@
"kind": "module", "kind": "module",
"path": "docforge.cli.commands.mkdocs_utils", "path": "docforge.cli.commands.mkdocs_utils",
"signature": "<bound method Alias.signature of Alias('mkdocs_utils', 'docforge.cli.mkdocs_utils')>", "signature": "<bound method Alias.signature of Alias('mkdocs_utils', 'docforge.cli.mkdocs_utils')>",
"docstring": "# Summary\n\nUtilities for working with MkDocs in the doc-forge CLI.", "docstring": null,
"members": { "members": {
"Path": { "Path": {
"name": "Path", "name": "Path",
@@ -95,21 +95,21 @@
"kind": "class", "kind": "class",
"path": "docforge.cli.commands.mkdocs_utils.GriffeLoader", "path": "docforge.cli.commands.mkdocs_utils.GriffeLoader",
"signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.cli.mkdocs_utils.GriffeLoader')>", "signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.cli.mkdocs_utils.GriffeLoader')>",
"docstring": "Load Python modules using Griffe and convert them into doc-forge models.\n\nThis loader uses the Griffe introspection engine to analyze Python source\ncode and transform the extracted information into `Project`, `Module`,\nand `DocObject` instances used by doc-forge.", "docstring": "Loads Python modules and extracts documentation using the Griffe introspection engine.",
"members": { "members": {
"load_project": { "load_project": {
"name": "load_project", "name": "load_project",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.GriffeLoader.load_project", "path": "docforge.cli.commands.mkdocs_utils.GriffeLoader.load_project",
"signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>", "signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>",
"docstring": "Load multiple modules and assemble them into a Project model.\n\nEach module path is introspected and converted into a `Module`\ninstance. All modules are then aggregated into a single `Project`\nobject.\n\nArgs:\n module_paths (List[str]):\n List of dotted module import paths to load.\n\n project_name (str, optional):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool, optional):\n If True, modules that fail to load will be skipped instead of raising an error.\n\nReturns:\n Project:\n A populated `Project` instance containing the loaded modules.\n\nRaises:\n ValueError:\n If no module paths are provided.\n\n ImportError:\n If a module fails to load and `skip_import_errors` is False." "docstring": "Load multiple modules and combine them into a single Project models.\n\nArgs:\n module_paths: A list of dotted paths to the modules to load.\n project_name: Optional name for the project. Defaults to the first module name.\n skip_import_errors: If True, modules that fail to import will be skipped.\n\nReturns:\n A Project instance containing the loaded modules."
}, },
"load_module": { "load_module": {
"name": "load_module", "name": "load_module",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.GriffeLoader.load_module", "path": "docforge.cli.commands.mkdocs_utils.GriffeLoader.load_module",
"signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>", "signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>",
"docstring": "Load and convert a single Python module.\n\nThe module is introspected using Griffe and then transformed into\na doc-forge `Module` model.\n\nArgs:\n path (str):\n Dotted import path of the module.\n\nReturns:\n Module:\n A populated `Module` instance." "docstring": "Load a single module and convert its introspection data into the docforge models.\n\nArgs:\n path: The dotted path of the module to load.\n\nReturns:\n A Module instance."
} }
} }
}, },
@@ -118,14 +118,14 @@
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.discover_module_paths", "path": "docforge.cli.commands.mkdocs_utils.discover_module_paths",
"signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.cli.mkdocs_utils.discover_module_paths')>", "signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.cli.mkdocs_utils.discover_module_paths')>",
"docstring": "Discover Python modules within a package directory.\n\nThe function scans the filesystem for `.py` files inside the specified\npackage and converts them into dotted module import paths.\n\nDiscovery rules:\n\n- Directories containing `__init__.py` are treated as packages.\n- Each `.py` file is treated as a module.\n- Results are returned as dotted import paths.\n\nArgs:\n module_name (str):\n Top-level package name to discover modules from.\n\n project_root (Path, optional):\n Root directory used to resolve module paths. If not provided, the\n current working directory is used.\n\nReturns:\n List[str]:\n A sorted list of unique dotted module import paths.\n\nRaises:\n FileNotFoundError:\n If the specified package directory does not exist." "docstring": "Discover all Python modules under a package via filesystem traversal.\n\nRules:\n- Directory with __init__.py is treated as a package.\n- Any .py file is treated as a module.\n- All paths are converted to dotted module paths.\n\nArgs:\n module_name: The name of the package to discover.\n project_root: The root directory of the project. Defaults to current working directory.\n\nReturns:\n A sorted list of dotted module paths."
}, },
"MkDocsRenderer": { "MkDocsRenderer": {
"name": "MkDocsRenderer", "name": "MkDocsRenderer",
"kind": "class", "kind": "class",
"path": "docforge.cli.commands.mkdocs_utils.MkDocsRenderer", "path": "docforge.cli.commands.mkdocs_utils.MkDocsRenderer",
"signature": "<bound method Alias.signature of Alias('MkDocsRenderer', 'docforge.cli.mkdocs_utils.MkDocsRenderer')>", "signature": "<bound method Alias.signature of Alias('MkDocsRenderer', 'docforge.cli.mkdocs_utils.MkDocsRenderer')>",
"docstring": "Renderer that produces Markdown documentation for MkDocs.\n\nGenerated pages use mkdocstrings directives to reference Python modules,\nallowing MkDocs to render API documentation dynamically.", "docstring": "Renderer that generates Markdown source files formatted for the MkDocs\n'mkdocstrings' plugin.",
"members": { "members": {
"name": { "name": {
"name": "name", "name": "name",
@@ -139,14 +139,7 @@
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.MkDocsRenderer.generate_sources", "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')>", "signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources')>",
"docstring": "Generate Markdown documentation files for a project.\n\nThis method renders a documentation structure from the provided\nproject model and writes the resulting Markdown files to the\nspecified output directory.\n\nArgs:\n project (Project):\n Project model containing modules to document.\n\n out_dir (Path):\n Directory where generated Markdown files will be written.\n\n module_is_source (bool, optional):\n If True, treat the specified module as the documentation root\n rather than nesting it inside a folder." "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."
},
"generate_readme": {
"name": "generate_readme",
"kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.MkDocsRenderer.generate_readme",
"signature": "<bound method Alias.signature of Alias('generate_readme', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_readme')>",
"docstring": "Generate a `README.md` file from the root module docstring.\n\nBehavior:\n\n- If `module_is_source` is True, `README.md` is written to the project\n root directory.\n- If False, README generation is currently not implemented.\n\nArgs:\n project (Project):\n Project model containing documentation metadata.\n\n docs_dir (Path):\n Directory containing generated documentation sources.\n\n module_is_source (bool, optional):\n Whether the module is treated as the project source root."
} }
} }
}, },
@@ -155,28 +148,28 @@
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.load_nav_spec", "path": "docforge.cli.commands.mkdocs_utils.load_nav_spec",
"signature": "<bound method Alias.signature of Alias('load_nav_spec', 'docforge.cli.mkdocs_utils.load_nav_spec')>", "signature": "<bound method Alias.signature of Alias('load_nav_spec', 'docforge.cli.mkdocs_utils.load_nav_spec')>",
"docstring": "Load a navigation specification file.\n\nThis helper function reads a YAML navigation file and constructs a\ncorresponding ``NavSpec`` instance.\n\nArgs:\n path: Path to the navigation specification file.\n\nReturns:\n A ``NavSpec`` instance representing the parsed specification.\n\nRaises:\n FileNotFoundError: If the specification file does not exist.\n ValueError: If the YAML structure is invalid." "docstring": "Utility function to load a NavSpec from a file.\n\nArgs:\n path: Path to the navigation specification file.\n\nReturns:\n A loaded NavSpec instance."
}, },
"resolve_nav": { "resolve_nav": {
"name": "resolve_nav", "name": "resolve_nav",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.resolve_nav", "path": "docforge.cli.commands.mkdocs_utils.resolve_nav",
"signature": "<bound method Alias.signature of Alias('resolve_nav', 'docforge.cli.mkdocs_utils.resolve_nav')>", "signature": "<bound method Alias.signature of Alias('resolve_nav', 'docforge.cli.mkdocs_utils.resolve_nav')>",
"docstring": "Resolve a navigation specification against the filesystem.\n\nThe function expands glob patterns defined in a ``NavSpec`` and verifies\nthat referenced documentation files exist within the documentation root.\n\nArgs:\n spec: Navigation specification describing documentation layout.\n docs_root: Root directory containing documentation Markdown files.\n\nReturns:\n A ``ResolvedNav`` instance containing validated navigation paths.\n\nRaises:\n FileNotFoundError: If the documentation root does not exist or a\n navigation pattern does not match any files." "docstring": "Create a ResolvedNav by processing a NavSpec against the filesystem.\nThis expands globs and validates the existence of referenced files.\n\nArgs:\n spec: The navigation specification to resolve.\n docs_root: The root directory for documentation files.\n\nReturns:\n A ResolvedNav instance.\n\nRaises:\n FileNotFoundError: If a pattern doesn't match any files or the docs_root doesn't exist."
}, },
"MkDocsNavEmitter": { "MkDocsNavEmitter": {
"name": "MkDocsNavEmitter", "name": "MkDocsNavEmitter",
"kind": "class", "kind": "class",
"path": "docforge.cli.commands.mkdocs_utils.MkDocsNavEmitter", "path": "docforge.cli.commands.mkdocs_utils.MkDocsNavEmitter",
"signature": "<bound method Alias.signature of Alias('MkDocsNavEmitter', 'docforge.cli.mkdocs_utils.MkDocsNavEmitter')>", "signature": "<bound method Alias.signature of Alias('MkDocsNavEmitter', 'docforge.cli.mkdocs_utils.MkDocsNavEmitter')>",
"docstring": "Emit MkDocs navigation structures from resolved navigation data.\n\nThe emitter transforms a ``ResolvedNav`` object into the YAML-compatible\nlist structure expected by the MkDocs ``nav`` configuration field.", "docstring": "Emitter responsible for transforming a ResolvedNav into an MkDocs-compatible\nnavigation structure.",
"members": { "members": {
"emit": { "emit": {
"name": "emit", "name": "emit",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.MkDocsNavEmitter.emit", "path": "docforge.cli.commands.mkdocs_utils.MkDocsNavEmitter.emit",
"signature": "<bound method Alias.signature of Alias('emit', 'docforge.nav.mkdocs.MkDocsNavEmitter.emit')>", "signature": "<bound method Alias.signature of Alias('emit', 'docforge.nav.mkdocs.MkDocsNavEmitter.emit')>",
"docstring": "Generate a navigation structure for ``mkdocs.yml``.\n\nArgs:\n nav: Resolved navigation data describing documentation groups\n and their associated Markdown files.\n\nReturns:\n A list of dictionaries representing the MkDocs navigation layout.\n Each dictionary maps a navigation label to a page or a list of\n pages." "docstring": "Generate a list of navigation entries for mkdocs.yml.\n\nArgs:\n nav: The resolved navigation data.\n\nReturns:\n A list of dictionary mappings representing the MkDocs navigation."
} }
} }
}, },
@@ -185,28 +178,28 @@
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.generate_sources", "path": "docforge.cli.commands.mkdocs_utils.generate_sources",
"signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.cli.mkdocs_utils.generate_sources')>", "signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.cli.mkdocs_utils.generate_sources')>",
"docstring": "Generate MkDocs Markdown sources for a Python module.\n\nThis function introspects the specified module, builds the internal\ndocumentation model, and renders Markdown documentation files for\nuse with MkDocs.\n\nArgs:\n module (str):\n Python module import path used as the entry point for\n documentation generation.\n\n docs_dir (Path):\n Directory where the generated Markdown files will be written.\n\n project_name (Optional[str]):\n Optional override for the project name used in documentation metadata.\n\n module_is_source (Optional[bool]):\n If True, treat the specified module directory as the project root\n rather than a nested module." "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."
}, },
"generate_config": { "generate_config": {
"name": "generate_config", "name": "generate_config",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.generate_config", "path": "docforge.cli.commands.mkdocs_utils.generate_config",
"signature": "<bound method Alias.signature of Alias('generate_config', 'docforge.cli.mkdocs_utils.generate_config')>", "signature": "<bound method Alias.signature of Alias('generate_config', 'docforge.cli.mkdocs_utils.generate_config')>",
"docstring": "Generate an `mkdocs.yml` configuration file.\n\nThe configuration is created by combining a template configuration\nwith a navigation structure derived from the docforge navigation\nspecification.\n\nArgs:\n docs_dir (Path):\n Directory containing generated documentation Markdown files.\n\n nav_file (Path):\n Path to the `docforge.nav.yml` navigation specification.\n\n template (Optional[Path]):\n Optional path to a custom MkDocs configuration template. If not\n provided, a built-in template will be used.\n\n out (Path):\n Destination path where the generated `mkdocs.yml` file will be written.\n\n site_name (str):\n Display name for the generated documentation site.\n\nRaises:\n click.FileError:\n If the navigation specification or template file cannot be found." "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": { "build": {
"name": "build", "name": "build",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.build", "path": "docforge.cli.commands.mkdocs_utils.build",
"signature": "<bound method Alias.signature of Alias('build', 'docforge.cli.mkdocs_utils.build')>", "signature": "<bound method Alias.signature of Alias('build', 'docforge.cli.mkdocs_utils.build')>",
"docstring": "Build the MkDocs documentation site.\n\nThis function loads the MkDocs configuration and runs the MkDocs\nbuild command to generate the final static documentation site.\n\nArgs:\n mkdocs_yml (Path):\n Path to the `mkdocs.yml` configuration file.\n\nRaises:\n click.ClickException:\n If the configuration file does not exist." "docstring": "Build the documentation site using MkDocs.\n\nArgs:\n mkdocs_yml: Path to the mkdocs.yml configuration file."
}, },
"serve": { "serve": {
"name": "serve", "name": "serve",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.serve", "path": "docforge.cli.commands.mkdocs_utils.serve",
"signature": "<bound method Alias.signature of Alias('serve', 'docforge.cli.mkdocs_utils.serve')>", "signature": "<bound method Alias.signature of Alias('serve', 'docforge.cli.mkdocs_utils.serve')>",
"docstring": "Start an MkDocs development server with live reload.\n\nThe server watches documentation files and automatically reloads\nthe site when changes are detected.\n\nArgs:\n mkdocs_yml (Path):\n Path to the `mkdocs.yml` configuration file.\n\nRaises:\n click.ClickException:\n If the configuration file does not exist." "docstring": "Serve the documentation site with live-reload using MkDocs.\n\nArgs:\n mkdocs_yml: Path to the mkdocs.yml configuration file."
} }
} }
}, },
@@ -215,7 +208,7 @@
"kind": "module", "kind": "module",
"path": "docforge.cli.commands.mcp_utils", "path": "docforge.cli.commands.mcp_utils",
"signature": "<bound method Alias.signature of Alias('mcp_utils', 'docforge.cli.mcp_utils')>", "signature": "<bound method Alias.signature of Alias('mcp_utils', 'docforge.cli.mcp_utils')>",
"docstring": "# Summary\n\nUtilities for working with MCP in the doc-forge CLI.", "docstring": null,
"members": { "members": {
"Path": { "Path": {
"name": "Path", "name": "Path",
@@ -236,21 +229,21 @@
"kind": "class", "kind": "class",
"path": "docforge.cli.commands.mcp_utils.GriffeLoader", "path": "docforge.cli.commands.mcp_utils.GriffeLoader",
"signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.cli.mcp_utils.GriffeLoader')>", "signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.cli.mcp_utils.GriffeLoader')>",
"docstring": "Load Python modules using Griffe and convert them into doc-forge models.\n\nThis loader uses the Griffe introspection engine to analyze Python source\ncode and transform the extracted information into `Project`, `Module`,\nand `DocObject` instances used by doc-forge.", "docstring": "Loads Python modules and extracts documentation using the Griffe introspection engine.",
"members": { "members": {
"load_project": { "load_project": {
"name": "load_project", "name": "load_project",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.mcp_utils.GriffeLoader.load_project", "path": "docforge.cli.commands.mcp_utils.GriffeLoader.load_project",
"signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>", "signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>",
"docstring": "Load multiple modules and assemble them into a Project model.\n\nEach module path is introspected and converted into a `Module`\ninstance. All modules are then aggregated into a single `Project`\nobject.\n\nArgs:\n module_paths (List[str]):\n List of dotted module import paths to load.\n\n project_name (str, optional):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool, optional):\n If True, modules that fail to load will be skipped instead of raising an error.\n\nReturns:\n Project:\n A populated `Project` instance containing the loaded modules.\n\nRaises:\n ValueError:\n If no module paths are provided.\n\n ImportError:\n If a module fails to load and `skip_import_errors` is False." "docstring": "Load multiple modules and combine them into a single Project models.\n\nArgs:\n module_paths: A list of dotted paths to the modules to load.\n project_name: Optional name for the project. Defaults to the first module name.\n skip_import_errors: If True, modules that fail to import will be skipped.\n\nReturns:\n A Project instance containing the loaded modules."
}, },
"load_module": { "load_module": {
"name": "load_module", "name": "load_module",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.mcp_utils.GriffeLoader.load_module", "path": "docforge.cli.commands.mcp_utils.GriffeLoader.load_module",
"signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>", "signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>",
"docstring": "Load and convert a single Python module.\n\nThe module is introspected using Griffe and then transformed into\na doc-forge `Module` model.\n\nArgs:\n path (str):\n Dotted import path of the module.\n\nReturns:\n Module:\n A populated `Module` instance." "docstring": "Load a single module and convert its introspection data into the docforge models.\n\nArgs:\n path: The dotted path of the module to load.\n\nReturns:\n A Module instance."
} }
} }
}, },
@@ -259,14 +252,14 @@
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.mcp_utils.discover_module_paths", "path": "docforge.cli.commands.mcp_utils.discover_module_paths",
"signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.cli.mcp_utils.discover_module_paths')>", "signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.cli.mcp_utils.discover_module_paths')>",
"docstring": "Discover Python modules within a package directory.\n\nThe function scans the filesystem for `.py` files inside the specified\npackage and converts them into dotted module import paths.\n\nDiscovery rules:\n\n- Directories containing `__init__.py` are treated as packages.\n- Each `.py` file is treated as a module.\n- Results are returned as dotted import paths.\n\nArgs:\n module_name (str):\n Top-level package name to discover modules from.\n\n project_root (Path, optional):\n Root directory used to resolve module paths. If not provided, the\n current working directory is used.\n\nReturns:\n List[str]:\n A sorted list of unique dotted module import paths.\n\nRaises:\n FileNotFoundError:\n If the specified package directory does not exist." "docstring": "Discover all Python modules under a package via filesystem traversal.\n\nRules:\n- Directory with __init__.py is treated as a package.\n- Any .py file is treated as a module.\n- All paths are converted to dotted module paths.\n\nArgs:\n module_name: The name of the package to discover.\n project_root: The root directory of the project. Defaults to current working directory.\n\nReturns:\n A sorted list of dotted module paths."
}, },
"MCPRenderer": { "MCPRenderer": {
"name": "MCPRenderer", "name": "MCPRenderer",
"kind": "class", "kind": "class",
"path": "docforge.cli.commands.mcp_utils.MCPRenderer", "path": "docforge.cli.commands.mcp_utils.MCPRenderer",
"signature": "<bound method Alias.signature of Alias('MCPRenderer', 'docforge.cli.mcp_utils.MCPRenderer')>", "signature": "<bound method Alias.signature of Alias('MCPRenderer', 'docforge.cli.mcp_utils.MCPRenderer')>",
"docstring": "Renderer that generates MCP-compatible documentation resources.\n\nThis renderer converts doc-forge project models into structured JSON\nresources suitable for consumption by systems implementing the Model\nContext Protocol (MCP).", "docstring": "Renderer that emits MCP-native JSON resources from docforge models.",
"members": { "members": {
"name": { "name": {
"name": "name", "name": "name",
@@ -280,7 +273,7 @@
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.mcp_utils.MCPRenderer.generate_sources", "path": "docforge.cli.commands.mcp_utils.MCPRenderer.generate_sources",
"signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mcp_renderer.MCPRenderer.generate_sources')>", "signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mcp_renderer.MCPRenderer.generate_sources')>",
"docstring": "Generate MCP documentation resources for a project.\n\nThe renderer serializes each module into a JSON resource and produces\nsupporting metadata files such as `nav.json` and `index.json`.\n\nArgs:\n project (Project):\n Documentation project model to render.\n\n out_dir (Path):\n Directory where MCP resources will be written." "docstring": "Generate MCP-compatible JSON resources and navigation for the project.\n\nArgs:\n project: The project model to render.\n out_dir: Target directory for the generated JSON files."
} }
} }
}, },
@@ -289,7 +282,7 @@
"kind": "class", "kind": "class",
"path": "docforge.cli.commands.mcp_utils.MCPServer", "path": "docforge.cli.commands.mcp_utils.MCPServer",
"signature": "<bound method Alias.signature of Alias('MCPServer', 'docforge.cli.mcp_utils.MCPServer')>", "signature": "<bound method Alias.signature of Alias('MCPServer', 'docforge.cli.mcp_utils.MCPServer')>",
"docstring": "MCP server for serving a pre-generated documentation bundle.\n\nThe server exposes documentation resources and diagnostic tools through\nMCP endpoints backed by JSON files generated by the MCP renderer.", "docstring": "MCP server for serving a pre-built MCP documentation bundle.",
"members": { "members": {
"mcp_root": { "mcp_root": {
"name": "mcp_root", "name": "mcp_root",
@@ -310,7 +303,7 @@
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.mcp_utils.MCPServer.run", "path": "docforge.cli.commands.mcp_utils.MCPServer.run",
"signature": "<bound method Alias.signature of Alias('run', 'docforge.servers.mcp_server.MCPServer.run')>", "signature": "<bound method Alias.signature of Alias('run', 'docforge.servers.mcp_server.MCPServer.run')>",
"docstring": "Start the MCP server.\n\nArgs:\n transport (Literal[\"stdio\", \"sse\", \"streamable-http\"]):\n Transport mechanism used by the MCP server. Supported options\n include `stdio`, `sse`, and `streamable-http`." "docstring": "Start the MCP server.\n\nArgs:\n transport: MCP transport (default: streamable-http)"
} }
} }
}, },
@@ -319,14 +312,14 @@
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.mcp_utils.generate_resources", "path": "docforge.cli.commands.mcp_utils.generate_resources",
"signature": "<bound method Alias.signature of Alias('generate_resources', 'docforge.cli.mcp_utils.generate_resources')>", "signature": "<bound method Alias.signature of Alias('generate_resources', 'docforge.cli.mcp_utils.generate_resources')>",
"docstring": "Generate MCP documentation resources from a Python module.\n\nThe function performs project introspection, builds the internal\ndocumentation model, and renders MCP-compatible JSON resources\nto the specified output directory.\n\nArgs:\n module (str):\n Python module import path used as the entry point for\n documentation generation.\n\n project_name (Optional[str]):\n Optional override for the project name used in generated\n documentation metadata.\n\n out_dir (Path):\n Directory where MCP resources (index.json, nav.json, and module data)\n will be written." "docstring": "Generate MCP-compatible documentation resources.\n\nArgs:\n module: The dotted path of the primary module to document.\n project_name: Optional override for the project name.\n out_dir: Directory where the MCP JSON resources and nav will be written."
}, },
"serve": { "serve": {
"name": "serve", "name": "serve",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.mcp_utils.serve", "path": "docforge.cli.commands.mcp_utils.serve",
"signature": "<bound method Alias.signature of Alias('serve', 'docforge.cli.mcp_utils.serve')>", "signature": "<bound method Alias.signature of Alias('serve', 'docforge.cli.mcp_utils.serve')>",
"docstring": "Start an MCP server for a pre-generated documentation bundle.\n\nThe server exposes documentation resources such as project metadata,\nnavigation structure, and module documentation through MCP endpoints.\n\nArgs:\n module (str):\n Python module import path used to identify the served\n documentation instance.\n\n mcp_root (Path):\n Path to the directory containing the MCP documentation\n bundle (index.json, nav.json, and modules/).\n\nRaises:\n click.ClickException:\n If the MCP documentation bundle is missing required files or directories." "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/."
} }
} }
}, },
@@ -341,22 +334,22 @@
"name": "build", "name": "build",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.build", "path": "docforge.cli.commands.build",
"signature": "<bound method Function.signature of Function('build', 28, 136)>", "signature": "<bound method Function.signature of Function('build', 18, 89)>",
"docstring": "Build documentation artifacts.\n\nThis command performs the full documentation build pipeline:\n\n1. Introspects the Python project using Griffe\n2. Generates renderer-specific documentation sources\n3. Optionally builds the final documentation output\n\nDepending on the selected options, the build can target:\n\n- MkDocs static documentation sites\n- MCP structured documentation resources\n\nArgs:\n mcp (bool):\n Enable MCP documentation generation.\n\n mkdocs (bool):\n Enable MkDocs documentation generation.\n\n module_is_source (bool):\n Treat the specified module directory as the project root.\n\n module (Optional[str]):\n Python module import path to document.\n\n project_name (Optional[str]):\n Optional override for the project name.\n\n site_name (Optional[str]):\n Display name for the MkDocs site.\n\n docs_dir (Path):\n Directory where Markdown documentation sources will be generated.\n\n nav_file (Path):\n Path to the navigation specification file.\n\n template (Optional[Path]):\n Optional custom MkDocs configuration template.\n\n mkdocs_yml (Path):\n Output path for the generated MkDocs configuration.\n\n out_dir (Path):\n Output directory for generated MCP resources.\n\nRaises:\n click.UsageError:\n If required options are missing or conflicting." "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."
}, },
"serve": { "serve": {
"name": "serve", "name": "serve",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.serve", "path": "docforge.cli.commands.serve",
"signature": "<bound method Function.signature of Function('serve', 139, 190)>", "signature": "<bound method Function.signature of Function('serve', 92, 120)>",
"docstring": "Serve generated documentation locally.\n\nDepending on the selected mode, this command starts either:\n\n- A MkDocs development server for browsing documentation\n- An MCP server exposing structured documentation resources\n\nArgs:\n mcp (bool):\n Serve documentation using the MCP server.\n\n mkdocs (bool):\n Serve the MkDocs development site.\n\n module (Optional[str]):\n Python module import path to serve via MCP.\n\n mkdocs_yml (Path):\n Path to the MkDocs configuration file.\n\n out_dir (Path):\n Root directory containing MCP documentation resources.\n\nRaises:\n click.UsageError:\n If invalid or conflicting options are provided." "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."
}, },
"tree": { "tree": {
"name": "tree", "name": "tree",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.tree", "path": "docforge.cli.commands.tree",
"signature": "<bound method Function.signature of Function('tree', 193, 229)>", "signature": "<bound method Function.signature of Function('tree', 123, 153)>",
"docstring": "Display the documentation object tree for a module.\n\nThis command introspects the specified module and prints a\nhierarchical representation of the discovered documentation\nobjects, including modules, classes, functions, and members.\n\nArgs:\n module (str):\n Python module import path to introspect.\n\n project_name (Optional[str]):\n Optional name to display as the project root." "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."
}, },
"Group": { "Group": {
"name": "Group", "name": "Group",

158
mcp_docs/modules/docforge.cli.json
View File

@@ -2,14 +2,14 @@
"module": "docforge.cli", "module": "docforge.cli",
"content": { "content": {
"path": "docforge.cli", "path": "docforge.cli",
"docstring": "# Summary\n\nCommand line interface entry point for doc-forge.\n\nThis module exposes the primary CLI entry function used by the\n`doc-forge` command. The actual command implementation resides in\n`docforge.cli.main`, while this module provides a stable import path\nfor external tools and the package entry point configuration.\n\nThe CLI is responsible for orchestrating documentation workflows such as\ngenerating renderer sources, building documentation sites, exporting\nmachine-readable documentation bundles, and starting development or MCP\nservers.\n\n---\n\n# Typical usage\n\nThe CLI is normally invoked through the installed command:\n\n```bash\ndoc-forge <command> [options]\n```\n\nProgrammatic invocation is also possible:\n\nExample:\n\n ```python\n from docforge.cli import main\n main()\n ```\n\n---", "docstring": "# CLI Layer\n\nThe `docforge.cli` package provides the command-line interface for interacting\nwith doc-forge.\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.",
"objects": { "objects": {
"main": { "main": {
"name": "main", "name": "main",
"kind": "module", "kind": "module",
"path": "docforge.cli.main", "path": "docforge.cli.main",
"signature": null, "signature": null,
"docstring": "# Summary\n\nCommand-line entry point for the doc-forge CLI.\n\nThis module exposes the executable entry point that initializes the\nClick command group defined in `docforge.cli.commands`.", "docstring": "Main entry point for the doc-forge CLI. This module delegates all command\nexecution to docforge.cli.commands.",
"members": { "members": {
"cli": { "cli": {
"name": "cli", "name": "cli",
@@ -22,8 +22,8 @@
"name": "main", "name": "main",
"kind": "function", "kind": "function",
"path": "docforge.cli.main.main", "path": "docforge.cli.main.main",
"signature": "<bound method Function.signature of Function('main', 13, 21)>", "signature": "<bound method Function.signature of Function('main', 7, 11)>",
"docstring": "Run the doc-forge command-line interface.\n\nThis function initializes and executes the Click CLI application.\nIt is used as the console entry point when invoking `doc-forge`\nfrom the command line." "docstring": "CLI Entry point. Boots the click application."
} }
} }
}, },
@@ -32,7 +32,7 @@
"kind": "module", "kind": "module",
"path": "docforge.cli.commands", "path": "docforge.cli.commands",
"signature": null, "signature": null,
"docstring": "# Summary\n\nCommand definitions for the doc-forge CLI.\n\nProvides the CLI structure using Click, including build, serve, and tree commands.", "docstring": null,
"members": { "members": {
"click": { "click": {
"name": "click", "name": "click",
@@ -67,21 +67,21 @@
"kind": "class", "kind": "class",
"path": "docforge.cli.commands.GriffeLoader", "path": "docforge.cli.commands.GriffeLoader",
"signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.loaders.GriffeLoader')>", "signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.loaders.GriffeLoader')>",
"docstring": "Load Python modules using Griffe and convert them into doc-forge models.\n\nThis loader uses the Griffe introspection engine to analyze Python source\ncode and transform the extracted information into `Project`, `Module`,\nand `DocObject` instances used by doc-forge.", "docstring": "Loads Python modules and extracts documentation using the Griffe introspection engine.",
"members": { "members": {
"load_project": { "load_project": {
"name": "load_project", "name": "load_project",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.GriffeLoader.load_project", "path": "docforge.cli.commands.GriffeLoader.load_project",
"signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>", "signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>",
"docstring": "Load multiple modules and assemble them into a Project model.\n\nEach module path is introspected and converted into a `Module`\ninstance. All modules are then aggregated into a single `Project`\nobject.\n\nArgs:\n module_paths (List[str]):\n List of dotted module import paths to load.\n\n project_name (str, optional):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool, optional):\n If True, modules that fail to load will be skipped instead of raising an error.\n\nReturns:\n Project:\n A populated `Project` instance containing the loaded modules.\n\nRaises:\n ValueError:\n If no module paths are provided.\n\n ImportError:\n If a module fails to load and `skip_import_errors` is False." "docstring": "Load multiple modules and combine them into a single Project models.\n\nArgs:\n module_paths: A list of dotted paths to the modules to load.\n project_name: Optional name for the project. Defaults to the first module name.\n skip_import_errors: If True, modules that fail to import will be skipped.\n\nReturns:\n A Project instance containing the loaded modules."
}, },
"load_module": { "load_module": {
"name": "load_module", "name": "load_module",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.GriffeLoader.load_module", "path": "docforge.cli.commands.GriffeLoader.load_module",
"signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>", "signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>",
"docstring": "Load and convert a single Python module.\n\nThe module is introspected using Griffe and then transformed into\na doc-forge `Module` model.\n\nArgs:\n path (str):\n Dotted import path of the module.\n\nReturns:\n Module:\n A populated `Module` instance." "docstring": "Load a single module and convert its introspection data into the docforge models.\n\nArgs:\n path: The dotted path of the module to load.\n\nReturns:\n A Module instance."
} }
} }
}, },
@@ -90,7 +90,7 @@
"kind": "module", "kind": "module",
"path": "docforge.cli.commands.mkdocs_utils", "path": "docforge.cli.commands.mkdocs_utils",
"signature": "<bound method Alias.signature of Alias('mkdocs_utils', 'docforge.cli.mkdocs_utils')>", "signature": "<bound method Alias.signature of Alias('mkdocs_utils', 'docforge.cli.mkdocs_utils')>",
"docstring": "# Summary\n\nUtilities for working with MkDocs in the doc-forge CLI.", "docstring": null,
"members": { "members": {
"Path": { "Path": {
"name": "Path", "name": "Path",
@@ -125,21 +125,21 @@
"kind": "class", "kind": "class",
"path": "docforge.cli.commands.mkdocs_utils.GriffeLoader", "path": "docforge.cli.commands.mkdocs_utils.GriffeLoader",
"signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.cli.mkdocs_utils.GriffeLoader')>", "signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.cli.mkdocs_utils.GriffeLoader')>",
"docstring": "Load Python modules using Griffe and convert them into doc-forge models.\n\nThis loader uses the Griffe introspection engine to analyze Python source\ncode and transform the extracted information into `Project`, `Module`,\nand `DocObject` instances used by doc-forge.", "docstring": "Loads Python modules and extracts documentation using the Griffe introspection engine.",
"members": { "members": {
"load_project": { "load_project": {
"name": "load_project", "name": "load_project",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.GriffeLoader.load_project", "path": "docforge.cli.commands.mkdocs_utils.GriffeLoader.load_project",
"signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>", "signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>",
"docstring": "Load multiple modules and assemble them into a Project model.\n\nEach module path is introspected and converted into a `Module`\ninstance. All modules are then aggregated into a single `Project`\nobject.\n\nArgs:\n module_paths (List[str]):\n List of dotted module import paths to load.\n\n project_name (str, optional):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool, optional):\n If True, modules that fail to load will be skipped instead of raising an error.\n\nReturns:\n Project:\n A populated `Project` instance containing the loaded modules.\n\nRaises:\n ValueError:\n If no module paths are provided.\n\n ImportError:\n If a module fails to load and `skip_import_errors` is False." "docstring": "Load multiple modules and combine them into a single Project models.\n\nArgs:\n module_paths: A list of dotted paths to the modules to load.\n project_name: Optional name for the project. Defaults to the first module name.\n skip_import_errors: If True, modules that fail to import will be skipped.\n\nReturns:\n A Project instance containing the loaded modules."
}, },
"load_module": { "load_module": {
"name": "load_module", "name": "load_module",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.GriffeLoader.load_module", "path": "docforge.cli.commands.mkdocs_utils.GriffeLoader.load_module",
"signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>", "signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>",
"docstring": "Load and convert a single Python module.\n\nThe module is introspected using Griffe and then transformed into\na doc-forge `Module` model.\n\nArgs:\n path (str):\n Dotted import path of the module.\n\nReturns:\n Module:\n A populated `Module` instance." "docstring": "Load a single module and convert its introspection data into the docforge models.\n\nArgs:\n path: The dotted path of the module to load.\n\nReturns:\n A Module instance."
} }
} }
}, },
@@ -148,14 +148,14 @@
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.discover_module_paths", "path": "docforge.cli.commands.mkdocs_utils.discover_module_paths",
"signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.cli.mkdocs_utils.discover_module_paths')>", "signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.cli.mkdocs_utils.discover_module_paths')>",
"docstring": "Discover Python modules within a package directory.\n\nThe function scans the filesystem for `.py` files inside the specified\npackage and converts them into dotted module import paths.\n\nDiscovery rules:\n\n- Directories containing `__init__.py` are treated as packages.\n- Each `.py` file is treated as a module.\n- Results are returned as dotted import paths.\n\nArgs:\n module_name (str):\n Top-level package name to discover modules from.\n\n project_root (Path, optional):\n Root directory used to resolve module paths. If not provided, the\n current working directory is used.\n\nReturns:\n List[str]:\n A sorted list of unique dotted module import paths.\n\nRaises:\n FileNotFoundError:\n If the specified package directory does not exist." "docstring": "Discover all Python modules under a package via filesystem traversal.\n\nRules:\n- Directory with __init__.py is treated as a package.\n- Any .py file is treated as a module.\n- All paths are converted to dotted module paths.\n\nArgs:\n module_name: The name of the package to discover.\n project_root: The root directory of the project. Defaults to current working directory.\n\nReturns:\n A sorted list of dotted module paths."
}, },
"MkDocsRenderer": { "MkDocsRenderer": {
"name": "MkDocsRenderer", "name": "MkDocsRenderer",
"kind": "class", "kind": "class",
"path": "docforge.cli.commands.mkdocs_utils.MkDocsRenderer", "path": "docforge.cli.commands.mkdocs_utils.MkDocsRenderer",
"signature": "<bound method Alias.signature of Alias('MkDocsRenderer', 'docforge.cli.mkdocs_utils.MkDocsRenderer')>", "signature": "<bound method Alias.signature of Alias('MkDocsRenderer', 'docforge.cli.mkdocs_utils.MkDocsRenderer')>",
"docstring": "Renderer that produces Markdown documentation for MkDocs.\n\nGenerated pages use mkdocstrings directives to reference Python modules,\nallowing MkDocs to render API documentation dynamically.", "docstring": "Renderer that generates Markdown source files formatted for the MkDocs\n'mkdocstrings' plugin.",
"members": { "members": {
"name": { "name": {
"name": "name", "name": "name",
@@ -169,14 +169,7 @@
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.MkDocsRenderer.generate_sources", "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')>", "signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources')>",
"docstring": "Generate Markdown documentation files for a project.\n\nThis method renders a documentation structure from the provided\nproject model and writes the resulting Markdown files to the\nspecified output directory.\n\nArgs:\n project (Project):\n Project model containing modules to document.\n\n out_dir (Path):\n Directory where generated Markdown files will be written.\n\n module_is_source (bool, optional):\n If True, treat the specified module as the documentation root\n rather than nesting it inside a folder." "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."
},
"generate_readme": {
"name": "generate_readme",
"kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.MkDocsRenderer.generate_readme",
"signature": "<bound method Alias.signature of Alias('generate_readme', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_readme')>",
"docstring": "Generate a `README.md` file from the root module docstring.\n\nBehavior:\n\n- If `module_is_source` is True, `README.md` is written to the project\n root directory.\n- If False, README generation is currently not implemented.\n\nArgs:\n project (Project):\n Project model containing documentation metadata.\n\n docs_dir (Path):\n Directory containing generated documentation sources.\n\n module_is_source (bool, optional):\n Whether the module is treated as the project source root."
} }
} }
}, },
@@ -185,28 +178,28 @@
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.load_nav_spec", "path": "docforge.cli.commands.mkdocs_utils.load_nav_spec",
"signature": "<bound method Alias.signature of Alias('load_nav_spec', 'docforge.cli.mkdocs_utils.load_nav_spec')>", "signature": "<bound method Alias.signature of Alias('load_nav_spec', 'docforge.cli.mkdocs_utils.load_nav_spec')>",
"docstring": "Load a navigation specification file.\n\nThis helper function reads a YAML navigation file and constructs a\ncorresponding ``NavSpec`` instance.\n\nArgs:\n path: Path to the navigation specification file.\n\nReturns:\n A ``NavSpec`` instance representing the parsed specification.\n\nRaises:\n FileNotFoundError: If the specification file does not exist.\n ValueError: If the YAML structure is invalid." "docstring": "Utility function to load a NavSpec from a file.\n\nArgs:\n path: Path to the navigation specification file.\n\nReturns:\n A loaded NavSpec instance."
}, },
"resolve_nav": { "resolve_nav": {
"name": "resolve_nav", "name": "resolve_nav",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.resolve_nav", "path": "docforge.cli.commands.mkdocs_utils.resolve_nav",
"signature": "<bound method Alias.signature of Alias('resolve_nav', 'docforge.cli.mkdocs_utils.resolve_nav')>", "signature": "<bound method Alias.signature of Alias('resolve_nav', 'docforge.cli.mkdocs_utils.resolve_nav')>",
"docstring": "Resolve a navigation specification against the filesystem.\n\nThe function expands glob patterns defined in a ``NavSpec`` and verifies\nthat referenced documentation files exist within the documentation root.\n\nArgs:\n spec: Navigation specification describing documentation layout.\n docs_root: Root directory containing documentation Markdown files.\n\nReturns:\n A ``ResolvedNav`` instance containing validated navigation paths.\n\nRaises:\n FileNotFoundError: If the documentation root does not exist or a\n navigation pattern does not match any files." "docstring": "Create a ResolvedNav by processing a NavSpec against the filesystem.\nThis expands globs and validates the existence of referenced files.\n\nArgs:\n spec: The navigation specification to resolve.\n docs_root: The root directory for documentation files.\n\nReturns:\n A ResolvedNav instance.\n\nRaises:\n FileNotFoundError: If a pattern doesn't match any files or the docs_root doesn't exist."
}, },
"MkDocsNavEmitter": { "MkDocsNavEmitter": {
"name": "MkDocsNavEmitter", "name": "MkDocsNavEmitter",
"kind": "class", "kind": "class",
"path": "docforge.cli.commands.mkdocs_utils.MkDocsNavEmitter", "path": "docforge.cli.commands.mkdocs_utils.MkDocsNavEmitter",
"signature": "<bound method Alias.signature of Alias('MkDocsNavEmitter', 'docforge.cli.mkdocs_utils.MkDocsNavEmitter')>", "signature": "<bound method Alias.signature of Alias('MkDocsNavEmitter', 'docforge.cli.mkdocs_utils.MkDocsNavEmitter')>",
"docstring": "Emit MkDocs navigation structures from resolved navigation data.\n\nThe emitter transforms a ``ResolvedNav`` object into the YAML-compatible\nlist structure expected by the MkDocs ``nav`` configuration field.", "docstring": "Emitter responsible for transforming a ResolvedNav into an MkDocs-compatible\nnavigation structure.",
"members": { "members": {
"emit": { "emit": {
"name": "emit", "name": "emit",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.MkDocsNavEmitter.emit", "path": "docforge.cli.commands.mkdocs_utils.MkDocsNavEmitter.emit",
"signature": "<bound method Alias.signature of Alias('emit', 'docforge.nav.mkdocs.MkDocsNavEmitter.emit')>", "signature": "<bound method Alias.signature of Alias('emit', 'docforge.nav.mkdocs.MkDocsNavEmitter.emit')>",
"docstring": "Generate a navigation structure for ``mkdocs.yml``.\n\nArgs:\n nav: Resolved navigation data describing documentation groups\n and their associated Markdown files.\n\nReturns:\n A list of dictionaries representing the MkDocs navigation layout.\n Each dictionary maps a navigation label to a page or a list of\n pages." "docstring": "Generate a list of navigation entries for mkdocs.yml.\n\nArgs:\n nav: The resolved navigation data.\n\nReturns:\n A list of dictionary mappings representing the MkDocs navigation."
} }
} }
}, },
@@ -215,28 +208,28 @@
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.generate_sources", "path": "docforge.cli.commands.mkdocs_utils.generate_sources",
"signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.cli.mkdocs_utils.generate_sources')>", "signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.cli.mkdocs_utils.generate_sources')>",
"docstring": "Generate MkDocs Markdown sources for a Python module.\n\nThis function introspects the specified module, builds the internal\ndocumentation model, and renders Markdown documentation files for\nuse with MkDocs.\n\nArgs:\n module (str):\n Python module import path used as the entry point for\n documentation generation.\n\n docs_dir (Path):\n Directory where the generated Markdown files will be written.\n\n project_name (Optional[str]):\n Optional override for the project name used in documentation metadata.\n\n module_is_source (Optional[bool]):\n If True, treat the specified module directory as the project root\n rather than a nested module." "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."
}, },
"generate_config": { "generate_config": {
"name": "generate_config", "name": "generate_config",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.generate_config", "path": "docforge.cli.commands.mkdocs_utils.generate_config",
"signature": "<bound method Alias.signature of Alias('generate_config', 'docforge.cli.mkdocs_utils.generate_config')>", "signature": "<bound method Alias.signature of Alias('generate_config', 'docforge.cli.mkdocs_utils.generate_config')>",
"docstring": "Generate an `mkdocs.yml` configuration file.\n\nThe configuration is created by combining a template configuration\nwith a navigation structure derived from the docforge navigation\nspecification.\n\nArgs:\n docs_dir (Path):\n Directory containing generated documentation Markdown files.\n\n nav_file (Path):\n Path to the `docforge.nav.yml` navigation specification.\n\n template (Optional[Path]):\n Optional path to a custom MkDocs configuration template. If not\n provided, a built-in template will be used.\n\n out (Path):\n Destination path where the generated `mkdocs.yml` file will be written.\n\n site_name (str):\n Display name for the generated documentation site.\n\nRaises:\n click.FileError:\n If the navigation specification or template file cannot be found." "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": { "build": {
"name": "build", "name": "build",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.build", "path": "docforge.cli.commands.mkdocs_utils.build",
"signature": "<bound method Alias.signature of Alias('build', 'docforge.cli.mkdocs_utils.build')>", "signature": "<bound method Alias.signature of Alias('build', 'docforge.cli.mkdocs_utils.build')>",
"docstring": "Build the MkDocs documentation site.\n\nThis function loads the MkDocs configuration and runs the MkDocs\nbuild command to generate the final static documentation site.\n\nArgs:\n mkdocs_yml (Path):\n Path to the `mkdocs.yml` configuration file.\n\nRaises:\n click.ClickException:\n If the configuration file does not exist." "docstring": "Build the documentation site using MkDocs.\n\nArgs:\n mkdocs_yml: Path to the mkdocs.yml configuration file."
}, },
"serve": { "serve": {
"name": "serve", "name": "serve",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.serve", "path": "docforge.cli.commands.mkdocs_utils.serve",
"signature": "<bound method Alias.signature of Alias('serve', 'docforge.cli.mkdocs_utils.serve')>", "signature": "<bound method Alias.signature of Alias('serve', 'docforge.cli.mkdocs_utils.serve')>",
"docstring": "Start an MkDocs development server with live reload.\n\nThe server watches documentation files and automatically reloads\nthe site when changes are detected.\n\nArgs:\n mkdocs_yml (Path):\n Path to the `mkdocs.yml` configuration file.\n\nRaises:\n click.ClickException:\n If the configuration file does not exist." "docstring": "Serve the documentation site with live-reload using MkDocs.\n\nArgs:\n mkdocs_yml: Path to the mkdocs.yml configuration file."
} }
} }
}, },
@@ -245,7 +238,7 @@
"kind": "module", "kind": "module",
"path": "docforge.cli.commands.mcp_utils", "path": "docforge.cli.commands.mcp_utils",
"signature": "<bound method Alias.signature of Alias('mcp_utils', 'docforge.cli.mcp_utils')>", "signature": "<bound method Alias.signature of Alias('mcp_utils', 'docforge.cli.mcp_utils')>",
"docstring": "# Summary\n\nUtilities for working with MCP in the doc-forge CLI.", "docstring": null,
"members": { "members": {
"Path": { "Path": {
"name": "Path", "name": "Path",
@@ -266,21 +259,21 @@
"kind": "class", "kind": "class",
"path": "docforge.cli.commands.mcp_utils.GriffeLoader", "path": "docforge.cli.commands.mcp_utils.GriffeLoader",
"signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.cli.mcp_utils.GriffeLoader')>", "signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.cli.mcp_utils.GriffeLoader')>",
"docstring": "Load Python modules using Griffe and convert them into doc-forge models.\n\nThis loader uses the Griffe introspection engine to analyze Python source\ncode and transform the extracted information into `Project`, `Module`,\nand `DocObject` instances used by doc-forge.", "docstring": "Loads Python modules and extracts documentation using the Griffe introspection engine.",
"members": { "members": {
"load_project": { "load_project": {
"name": "load_project", "name": "load_project",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.mcp_utils.GriffeLoader.load_project", "path": "docforge.cli.commands.mcp_utils.GriffeLoader.load_project",
"signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>", "signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>",
"docstring": "Load multiple modules and assemble them into a Project model.\n\nEach module path is introspected and converted into a `Module`\ninstance. All modules are then aggregated into a single `Project`\nobject.\n\nArgs:\n module_paths (List[str]):\n List of dotted module import paths to load.\n\n project_name (str, optional):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool, optional):\n If True, modules that fail to load will be skipped instead of raising an error.\n\nReturns:\n Project:\n A populated `Project` instance containing the loaded modules.\n\nRaises:\n ValueError:\n If no module paths are provided.\n\n ImportError:\n If a module fails to load and `skip_import_errors` is False." "docstring": "Load multiple modules and combine them into a single Project models.\n\nArgs:\n module_paths: A list of dotted paths to the modules to load.\n project_name: Optional name for the project. Defaults to the first module name.\n skip_import_errors: If True, modules that fail to import will be skipped.\n\nReturns:\n A Project instance containing the loaded modules."
}, },
"load_module": { "load_module": {
"name": "load_module", "name": "load_module",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.mcp_utils.GriffeLoader.load_module", "path": "docforge.cli.commands.mcp_utils.GriffeLoader.load_module",
"signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>", "signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>",
"docstring": "Load and convert a single Python module.\n\nThe module is introspected using Griffe and then transformed into\na doc-forge `Module` model.\n\nArgs:\n path (str):\n Dotted import path of the module.\n\nReturns:\n Module:\n A populated `Module` instance." "docstring": "Load a single module and convert its introspection data into the docforge models.\n\nArgs:\n path: The dotted path of the module to load.\n\nReturns:\n A Module instance."
} }
} }
}, },
@@ -289,14 +282,14 @@
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.mcp_utils.discover_module_paths", "path": "docforge.cli.commands.mcp_utils.discover_module_paths",
"signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.cli.mcp_utils.discover_module_paths')>", "signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.cli.mcp_utils.discover_module_paths')>",
"docstring": "Discover Python modules within a package directory.\n\nThe function scans the filesystem for `.py` files inside the specified\npackage and converts them into dotted module import paths.\n\nDiscovery rules:\n\n- Directories containing `__init__.py` are treated as packages.\n- Each `.py` file is treated as a module.\n- Results are returned as dotted import paths.\n\nArgs:\n module_name (str):\n Top-level package name to discover modules from.\n\n project_root (Path, optional):\n Root directory used to resolve module paths. If not provided, the\n current working directory is used.\n\nReturns:\n List[str]:\n A sorted list of unique dotted module import paths.\n\nRaises:\n FileNotFoundError:\n If the specified package directory does not exist." "docstring": "Discover all Python modules under a package via filesystem traversal.\n\nRules:\n- Directory with __init__.py is treated as a package.\n- Any .py file is treated as a module.\n- All paths are converted to dotted module paths.\n\nArgs:\n module_name: The name of the package to discover.\n project_root: The root directory of the project. Defaults to current working directory.\n\nReturns:\n A sorted list of dotted module paths."
}, },
"MCPRenderer": { "MCPRenderer": {
"name": "MCPRenderer", "name": "MCPRenderer",
"kind": "class", "kind": "class",
"path": "docforge.cli.commands.mcp_utils.MCPRenderer", "path": "docforge.cli.commands.mcp_utils.MCPRenderer",
"signature": "<bound method Alias.signature of Alias('MCPRenderer', 'docforge.cli.mcp_utils.MCPRenderer')>", "signature": "<bound method Alias.signature of Alias('MCPRenderer', 'docforge.cli.mcp_utils.MCPRenderer')>",
"docstring": "Renderer that generates MCP-compatible documentation resources.\n\nThis renderer converts doc-forge project models into structured JSON\nresources suitable for consumption by systems implementing the Model\nContext Protocol (MCP).", "docstring": "Renderer that emits MCP-native JSON resources from docforge models.",
"members": { "members": {
"name": { "name": {
"name": "name", "name": "name",
@@ -310,7 +303,7 @@
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.mcp_utils.MCPRenderer.generate_sources", "path": "docforge.cli.commands.mcp_utils.MCPRenderer.generate_sources",
"signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mcp_renderer.MCPRenderer.generate_sources')>", "signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mcp_renderer.MCPRenderer.generate_sources')>",
"docstring": "Generate MCP documentation resources for a project.\n\nThe renderer serializes each module into a JSON resource and produces\nsupporting metadata files such as `nav.json` and `index.json`.\n\nArgs:\n project (Project):\n Documentation project model to render.\n\n out_dir (Path):\n Directory where MCP resources will be written." "docstring": "Generate MCP-compatible JSON resources and navigation for the project.\n\nArgs:\n project: The project model to render.\n out_dir: Target directory for the generated JSON files."
} }
} }
}, },
@@ -319,7 +312,7 @@
"kind": "class", "kind": "class",
"path": "docforge.cli.commands.mcp_utils.MCPServer", "path": "docforge.cli.commands.mcp_utils.MCPServer",
"signature": "<bound method Alias.signature of Alias('MCPServer', 'docforge.cli.mcp_utils.MCPServer')>", "signature": "<bound method Alias.signature of Alias('MCPServer', 'docforge.cli.mcp_utils.MCPServer')>",
"docstring": "MCP server for serving a pre-generated documentation bundle.\n\nThe server exposes documentation resources and diagnostic tools through\nMCP endpoints backed by JSON files generated by the MCP renderer.", "docstring": "MCP server for serving a pre-built MCP documentation bundle.",
"members": { "members": {
"mcp_root": { "mcp_root": {
"name": "mcp_root", "name": "mcp_root",
@@ -340,7 +333,7 @@
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.mcp_utils.MCPServer.run", "path": "docforge.cli.commands.mcp_utils.MCPServer.run",
"signature": "<bound method Alias.signature of Alias('run', 'docforge.servers.mcp_server.MCPServer.run')>", "signature": "<bound method Alias.signature of Alias('run', 'docforge.servers.mcp_server.MCPServer.run')>",
"docstring": "Start the MCP server.\n\nArgs:\n transport (Literal[\"stdio\", \"sse\", \"streamable-http\"]):\n Transport mechanism used by the MCP server. Supported options\n include `stdio`, `sse`, and `streamable-http`." "docstring": "Start the MCP server.\n\nArgs:\n transport: MCP transport (default: streamable-http)"
} }
} }
}, },
@@ -349,14 +342,14 @@
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.mcp_utils.generate_resources", "path": "docforge.cli.commands.mcp_utils.generate_resources",
"signature": "<bound method Alias.signature of Alias('generate_resources', 'docforge.cli.mcp_utils.generate_resources')>", "signature": "<bound method Alias.signature of Alias('generate_resources', 'docforge.cli.mcp_utils.generate_resources')>",
"docstring": "Generate MCP documentation resources from a Python module.\n\nThe function performs project introspection, builds the internal\ndocumentation model, and renders MCP-compatible JSON resources\nto the specified output directory.\n\nArgs:\n module (str):\n Python module import path used as the entry point for\n documentation generation.\n\n project_name (Optional[str]):\n Optional override for the project name used in generated\n documentation metadata.\n\n out_dir (Path):\n Directory where MCP resources (index.json, nav.json, and module data)\n will be written." "docstring": "Generate MCP-compatible documentation resources.\n\nArgs:\n module: The dotted path of the primary module to document.\n project_name: Optional override for the project name.\n out_dir: Directory where the MCP JSON resources and nav will be written."
}, },
"serve": { "serve": {
"name": "serve", "name": "serve",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.mcp_utils.serve", "path": "docforge.cli.commands.mcp_utils.serve",
"signature": "<bound method Alias.signature of Alias('serve', 'docforge.cli.mcp_utils.serve')>", "signature": "<bound method Alias.signature of Alias('serve', 'docforge.cli.mcp_utils.serve')>",
"docstring": "Start an MCP server for a pre-generated documentation bundle.\n\nThe server exposes documentation resources such as project metadata,\nnavigation structure, and module documentation through MCP endpoints.\n\nArgs:\n module (str):\n Python module import path used to identify the served\n documentation instance.\n\n mcp_root (Path):\n Path to the directory containing the MCP documentation\n bundle (index.json, nav.json, and modules/).\n\nRaises:\n click.ClickException:\n If the MCP documentation bundle is missing required files or directories." "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/."
} }
} }
}, },
@@ -371,22 +364,22 @@
"name": "build", "name": "build",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.build", "path": "docforge.cli.commands.build",
"signature": "<bound method Function.signature of Function('build', 28, 136)>", "signature": "<bound method Function.signature of Function('build', 18, 89)>",
"docstring": "Build documentation artifacts.\n\nThis command performs the full documentation build pipeline:\n\n1. Introspects the Python project using Griffe\n2. Generates renderer-specific documentation sources\n3. Optionally builds the final documentation output\n\nDepending on the selected options, the build can target:\n\n- MkDocs static documentation sites\n- MCP structured documentation resources\n\nArgs:\n mcp (bool):\n Enable MCP documentation generation.\n\n mkdocs (bool):\n Enable MkDocs documentation generation.\n\n module_is_source (bool):\n Treat the specified module directory as the project root.\n\n module (Optional[str]):\n Python module import path to document.\n\n project_name (Optional[str]):\n Optional override for the project name.\n\n site_name (Optional[str]):\n Display name for the MkDocs site.\n\n docs_dir (Path):\n Directory where Markdown documentation sources will be generated.\n\n nav_file (Path):\n Path to the navigation specification file.\n\n template (Optional[Path]):\n Optional custom MkDocs configuration template.\n\n mkdocs_yml (Path):\n Output path for the generated MkDocs configuration.\n\n out_dir (Path):\n Output directory for generated MCP resources.\n\nRaises:\n click.UsageError:\n If required options are missing or conflicting." "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."
}, },
"serve": { "serve": {
"name": "serve", "name": "serve",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.serve", "path": "docforge.cli.commands.serve",
"signature": "<bound method Function.signature of Function('serve', 139, 190)>", "signature": "<bound method Function.signature of Function('serve', 92, 120)>",
"docstring": "Serve generated documentation locally.\n\nDepending on the selected mode, this command starts either:\n\n- A MkDocs development server for browsing documentation\n- An MCP server exposing structured documentation resources\n\nArgs:\n mcp (bool):\n Serve documentation using the MCP server.\n\n mkdocs (bool):\n Serve the MkDocs development site.\n\n module (Optional[str]):\n Python module import path to serve via MCP.\n\n mkdocs_yml (Path):\n Path to the MkDocs configuration file.\n\n out_dir (Path):\n Root directory containing MCP documentation resources.\n\nRaises:\n click.UsageError:\n If invalid or conflicting options are provided." "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."
}, },
"tree": { "tree": {
"name": "tree", "name": "tree",
"kind": "function", "kind": "function",
"path": "docforge.cli.commands.tree", "path": "docforge.cli.commands.tree",
"signature": "<bound method Function.signature of Function('tree', 193, 229)>", "signature": "<bound method Function.signature of Function('tree', 123, 153)>",
"docstring": "Display the documentation object tree for a module.\n\nThis command introspects the specified module and prints a\nhierarchical representation of the discovered documentation\nobjects, including modules, classes, functions, and members.\n\nArgs:\n module (str):\n Python module import path to introspect.\n\n project_name (Optional[str]):\n Optional name to display as the project root." "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."
}, },
"Group": { "Group": {
"name": "Group", "name": "Group",
@@ -409,7 +402,7 @@
"kind": "module", "kind": "module",
"path": "docforge.cli.mcp_utils", "path": "docforge.cli.mcp_utils",
"signature": null, "signature": null,
"docstring": "# Summary\n\nUtilities for working with MCP in the doc-forge CLI.", "docstring": null,
"members": { "members": {
"Path": { "Path": {
"name": "Path", "name": "Path",
@@ -430,21 +423,21 @@
"kind": "class", "kind": "class",
"path": "docforge.cli.mcp_utils.GriffeLoader", "path": "docforge.cli.mcp_utils.GriffeLoader",
"signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.loaders.GriffeLoader')>", "signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.loaders.GriffeLoader')>",
"docstring": "Load Python modules using Griffe and convert them into doc-forge models.\n\nThis loader uses the Griffe introspection engine to analyze Python source\ncode and transform the extracted information into `Project`, `Module`,\nand `DocObject` instances used by doc-forge.", "docstring": "Loads Python modules and extracts documentation using the Griffe introspection engine.",
"members": { "members": {
"load_project": { "load_project": {
"name": "load_project", "name": "load_project",
"kind": "function", "kind": "function",
"path": "docforge.cli.mcp_utils.GriffeLoader.load_project", "path": "docforge.cli.mcp_utils.GriffeLoader.load_project",
"signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>", "signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>",
"docstring": "Load multiple modules and assemble them into a Project model.\n\nEach module path is introspected and converted into a `Module`\ninstance. All modules are then aggregated into a single `Project`\nobject.\n\nArgs:\n module_paths (List[str]):\n List of dotted module import paths to load.\n\n project_name (str, optional):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool, optional):\n If True, modules that fail to load will be skipped instead of raising an error.\n\nReturns:\n Project:\n A populated `Project` instance containing the loaded modules.\n\nRaises:\n ValueError:\n If no module paths are provided.\n\n ImportError:\n If a module fails to load and `skip_import_errors` is False." "docstring": "Load multiple modules and combine them into a single Project models.\n\nArgs:\n module_paths: A list of dotted paths to the modules to load.\n project_name: Optional name for the project. Defaults to the first module name.\n skip_import_errors: If True, modules that fail to import will be skipped.\n\nReturns:\n A Project instance containing the loaded modules."
}, },
"load_module": { "load_module": {
"name": "load_module", "name": "load_module",
"kind": "function", "kind": "function",
"path": "docforge.cli.mcp_utils.GriffeLoader.load_module", "path": "docforge.cli.mcp_utils.GriffeLoader.load_module",
"signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>", "signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>",
"docstring": "Load and convert a single Python module.\n\nThe module is introspected using Griffe and then transformed into\na doc-forge `Module` model.\n\nArgs:\n path (str):\n Dotted import path of the module.\n\nReturns:\n Module:\n A populated `Module` instance." "docstring": "Load a single module and convert its introspection data into the docforge models.\n\nArgs:\n path: The dotted path of the module to load.\n\nReturns:\n A Module instance."
} }
} }
}, },
@@ -453,14 +446,14 @@
"kind": "function", "kind": "function",
"path": "docforge.cli.mcp_utils.discover_module_paths", "path": "docforge.cli.mcp_utils.discover_module_paths",
"signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.loaders.discover_module_paths')>", "signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.loaders.discover_module_paths')>",
"docstring": "Discover Python modules within a package directory.\n\nThe function scans the filesystem for `.py` files inside the specified\npackage and converts them into dotted module import paths.\n\nDiscovery rules:\n\n- Directories containing `__init__.py` are treated as packages.\n- Each `.py` file is treated as a module.\n- Results are returned as dotted import paths.\n\nArgs:\n module_name (str):\n Top-level package name to discover modules from.\n\n project_root (Path, optional):\n Root directory used to resolve module paths. If not provided, the\n current working directory is used.\n\nReturns:\n List[str]:\n A sorted list of unique dotted module import paths.\n\nRaises:\n FileNotFoundError:\n If the specified package directory does not exist." "docstring": "Discover all Python modules under a package via filesystem traversal.\n\nRules:\n- Directory with __init__.py is treated as a package.\n- Any .py file is treated as a module.\n- All paths are converted to dotted module paths.\n\nArgs:\n module_name: The name of the package to discover.\n project_root: The root directory of the project. Defaults to current working directory.\n\nReturns:\n A sorted list of dotted module paths."
}, },
"MCPRenderer": { "MCPRenderer": {
"name": "MCPRenderer", "name": "MCPRenderer",
"kind": "class", "kind": "class",
"path": "docforge.cli.mcp_utils.MCPRenderer", "path": "docforge.cli.mcp_utils.MCPRenderer",
"signature": "<bound method Alias.signature of Alias('MCPRenderer', 'docforge.renderers.MCPRenderer')>", "signature": "<bound method Alias.signature of Alias('MCPRenderer', 'docforge.renderers.MCPRenderer')>",
"docstring": "Renderer that generates MCP-compatible documentation resources.\n\nThis renderer converts doc-forge project models into structured JSON\nresources suitable for consumption by systems implementing the Model\nContext Protocol (MCP).", "docstring": "Renderer that emits MCP-native JSON resources from docforge models.",
"members": { "members": {
"name": { "name": {
"name": "name", "name": "name",
@@ -474,7 +467,7 @@
"kind": "function", "kind": "function",
"path": "docforge.cli.mcp_utils.MCPRenderer.generate_sources", "path": "docforge.cli.mcp_utils.MCPRenderer.generate_sources",
"signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mcp_renderer.MCPRenderer.generate_sources')>", "signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mcp_renderer.MCPRenderer.generate_sources')>",
"docstring": "Generate MCP documentation resources for a project.\n\nThe renderer serializes each module into a JSON resource and produces\nsupporting metadata files such as `nav.json` and `index.json`.\n\nArgs:\n project (Project):\n Documentation project model to render.\n\n out_dir (Path):\n Directory where MCP resources will be written." "docstring": "Generate MCP-compatible JSON resources and navigation for the project.\n\nArgs:\n project: The project model to render.\n out_dir: Target directory for the generated JSON files."
} }
} }
}, },
@@ -483,7 +476,7 @@
"kind": "class", "kind": "class",
"path": "docforge.cli.mcp_utils.MCPServer", "path": "docforge.cli.mcp_utils.MCPServer",
"signature": "<bound method Alias.signature of Alias('MCPServer', 'docforge.servers.MCPServer')>", "signature": "<bound method Alias.signature of Alias('MCPServer', 'docforge.servers.MCPServer')>",
"docstring": "MCP server for serving a pre-generated documentation bundle.\n\nThe server exposes documentation resources and diagnostic tools through\nMCP endpoints backed by JSON files generated by the MCP renderer.", "docstring": "MCP server for serving a pre-built MCP documentation bundle.",
"members": { "members": {
"mcp_root": { "mcp_root": {
"name": "mcp_root", "name": "mcp_root",
@@ -504,7 +497,7 @@
"kind": "function", "kind": "function",
"path": "docforge.cli.mcp_utils.MCPServer.run", "path": "docforge.cli.mcp_utils.MCPServer.run",
"signature": "<bound method Alias.signature of Alias('run', 'docforge.servers.mcp_server.MCPServer.run')>", "signature": "<bound method Alias.signature of Alias('run', 'docforge.servers.mcp_server.MCPServer.run')>",
"docstring": "Start the MCP server.\n\nArgs:\n transport (Literal[\"stdio\", \"sse\", \"streamable-http\"]):\n Transport mechanism used by the MCP server. Supported options\n include `stdio`, `sse`, and `streamable-http`." "docstring": "Start the MCP server.\n\nArgs:\n transport: MCP transport (default: streamable-http)"
} }
} }
}, },
@@ -512,15 +505,15 @@
"name": "generate_resources", "name": "generate_resources",
"kind": "function", "kind": "function",
"path": "docforge.cli.mcp_utils.generate_resources", "path": "docforge.cli.mcp_utils.generate_resources",
"signature": "<bound method Function.signature of Function('generate_resources', 14, 40)>", "signature": "<bound method Function.signature of Function('generate_resources', 7, 21)>",
"docstring": "Generate MCP documentation resources from a Python module.\n\nThe function performs project introspection, builds the internal\ndocumentation model, and renders MCP-compatible JSON resources\nto the specified output directory.\n\nArgs:\n module (str):\n Python module import path used as the entry point for\n documentation generation.\n\n project_name (Optional[str]):\n Optional override for the project name used in generated\n documentation metadata.\n\n out_dir (Path):\n Directory where MCP resources (index.json, nav.json, and module data)\n will be written." "docstring": "Generate MCP-compatible documentation resources.\n\nArgs:\n module: The dotted path of the primary module to document.\n project_name: Optional override for the project name.\n out_dir: Directory where the MCP JSON resources and nav will be written."
}, },
"serve": { "serve": {
"name": "serve", "name": "serve",
"kind": "function", "kind": "function",
"path": "docforge.cli.mcp_utils.serve", "path": "docforge.cli.mcp_utils.serve",
"signature": "<bound method Function.signature of Function('serve', 43, 80)>", "signature": "<bound method Function.signature of Function('serve', 23, 47)>",
"docstring": "Start an MCP server for a pre-generated documentation bundle.\n\nThe server exposes documentation resources such as project metadata,\nnavigation structure, and module documentation through MCP endpoints.\n\nArgs:\n module (str):\n Python module import path used to identify the served\n documentation instance.\n\n mcp_root (Path):\n Path to the directory containing the MCP documentation\n bundle (index.json, nav.json, and modules/).\n\nRaises:\n click.ClickException:\n If the MCP documentation bundle is missing required files or directories." "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/."
} }
} }
}, },
@@ -529,7 +522,7 @@
"kind": "module", "kind": "module",
"path": "docforge.cli.mkdocs_utils", "path": "docforge.cli.mkdocs_utils",
"signature": null, "signature": null,
"docstring": "# Summary\n\nUtilities for working with MkDocs in the doc-forge CLI.", "docstring": null,
"members": { "members": {
"Path": { "Path": {
"name": "Path", "name": "Path",
@@ -564,21 +557,21 @@
"kind": "class", "kind": "class",
"path": "docforge.cli.mkdocs_utils.GriffeLoader", "path": "docforge.cli.mkdocs_utils.GriffeLoader",
"signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.loaders.GriffeLoader')>", "signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.loaders.GriffeLoader')>",
"docstring": "Load Python modules using Griffe and convert them into doc-forge models.\n\nThis loader uses the Griffe introspection engine to analyze Python source\ncode and transform the extracted information into `Project`, `Module`,\nand `DocObject` instances used by doc-forge.", "docstring": "Loads Python modules and extracts documentation using the Griffe introspection engine.",
"members": { "members": {
"load_project": { "load_project": {
"name": "load_project", "name": "load_project",
"kind": "function", "kind": "function",
"path": "docforge.cli.mkdocs_utils.GriffeLoader.load_project", "path": "docforge.cli.mkdocs_utils.GriffeLoader.load_project",
"signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>", "signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>",
"docstring": "Load multiple modules and assemble them into a Project model.\n\nEach module path is introspected and converted into a `Module`\ninstance. All modules are then aggregated into a single `Project`\nobject.\n\nArgs:\n module_paths (List[str]):\n List of dotted module import paths to load.\n\n project_name (str, optional):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool, optional):\n If True, modules that fail to load will be skipped instead of raising an error.\n\nReturns:\n Project:\n A populated `Project` instance containing the loaded modules.\n\nRaises:\n ValueError:\n If no module paths are provided.\n\n ImportError:\n If a module fails to load and `skip_import_errors` is False." "docstring": "Load multiple modules and combine them into a single Project models.\n\nArgs:\n module_paths: A list of dotted paths to the modules to load.\n project_name: Optional name for the project. Defaults to the first module name.\n skip_import_errors: If True, modules that fail to import will be skipped.\n\nReturns:\n A Project instance containing the loaded modules."
}, },
"load_module": { "load_module": {
"name": "load_module", "name": "load_module",
"kind": "function", "kind": "function",
"path": "docforge.cli.mkdocs_utils.GriffeLoader.load_module", "path": "docforge.cli.mkdocs_utils.GriffeLoader.load_module",
"signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>", "signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>",
"docstring": "Load and convert a single Python module.\n\nThe module is introspected using Griffe and then transformed into\na doc-forge `Module` model.\n\nArgs:\n path (str):\n Dotted import path of the module.\n\nReturns:\n Module:\n A populated `Module` instance." "docstring": "Load a single module and convert its introspection data into the docforge models.\n\nArgs:\n path: The dotted path of the module to load.\n\nReturns:\n A Module instance."
} }
} }
}, },
@@ -587,14 +580,14 @@
"kind": "function", "kind": "function",
"path": "docforge.cli.mkdocs_utils.discover_module_paths", "path": "docforge.cli.mkdocs_utils.discover_module_paths",
"signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.loaders.discover_module_paths')>", "signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.loaders.discover_module_paths')>",
"docstring": "Discover Python modules within a package directory.\n\nThe function scans the filesystem for `.py` files inside the specified\npackage and converts them into dotted module import paths.\n\nDiscovery rules:\n\n- Directories containing `__init__.py` are treated as packages.\n- Each `.py` file is treated as a module.\n- Results are returned as dotted import paths.\n\nArgs:\n module_name (str):\n Top-level package name to discover modules from.\n\n project_root (Path, optional):\n Root directory used to resolve module paths. If not provided, the\n current working directory is used.\n\nReturns:\n List[str]:\n A sorted list of unique dotted module import paths.\n\nRaises:\n FileNotFoundError:\n If the specified package directory does not exist." "docstring": "Discover all Python modules under a package via filesystem traversal.\n\nRules:\n- Directory with __init__.py is treated as a package.\n- Any .py file is treated as a module.\n- All paths are converted to dotted module paths.\n\nArgs:\n module_name: The name of the package to discover.\n project_root: The root directory of the project. Defaults to current working directory.\n\nReturns:\n A sorted list of dotted module paths."
}, },
"MkDocsRenderer": { "MkDocsRenderer": {
"name": "MkDocsRenderer", "name": "MkDocsRenderer",
"kind": "class", "kind": "class",
"path": "docforge.cli.mkdocs_utils.MkDocsRenderer", "path": "docforge.cli.mkdocs_utils.MkDocsRenderer",
"signature": "<bound method Alias.signature of Alias('MkDocsRenderer', 'docforge.renderers.MkDocsRenderer')>", "signature": "<bound method Alias.signature of Alias('MkDocsRenderer', 'docforge.renderers.MkDocsRenderer')>",
"docstring": "Renderer that produces Markdown documentation for MkDocs.\n\nGenerated pages use mkdocstrings directives to reference Python modules,\nallowing MkDocs to render API documentation dynamically.", "docstring": "Renderer that generates Markdown source files formatted for the MkDocs\n'mkdocstrings' plugin.",
"members": { "members": {
"name": { "name": {
"name": "name", "name": "name",
@@ -608,14 +601,7 @@
"kind": "function", "kind": "function",
"path": "docforge.cli.mkdocs_utils.MkDocsRenderer.generate_sources", "path": "docforge.cli.mkdocs_utils.MkDocsRenderer.generate_sources",
"signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources')>", "signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources')>",
"docstring": "Generate Markdown documentation files for a project.\n\nThis method renders a documentation structure from the provided\nproject model and writes the resulting Markdown files to the\nspecified output directory.\n\nArgs:\n project (Project):\n Project model containing modules to document.\n\n out_dir (Path):\n Directory where generated Markdown files will be written.\n\n module_is_source (bool, optional):\n If True, treat the specified module as the documentation root\n rather than nesting it inside a folder." "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."
},
"generate_readme": {
"name": "generate_readme",
"kind": "function",
"path": "docforge.cli.mkdocs_utils.MkDocsRenderer.generate_readme",
"signature": "<bound method Alias.signature of Alias('generate_readme', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_readme')>",
"docstring": "Generate a `README.md` file from the root module docstring.\n\nBehavior:\n\n- If `module_is_source` is True, `README.md` is written to the project\n root directory.\n- If False, README generation is currently not implemented.\n\nArgs:\n project (Project):\n Project model containing documentation metadata.\n\n docs_dir (Path):\n Directory containing generated documentation sources.\n\n module_is_source (bool, optional):\n Whether the module is treated as the project source root."
} }
} }
}, },
@@ -624,28 +610,28 @@
"kind": "function", "kind": "function",
"path": "docforge.cli.mkdocs_utils.load_nav_spec", "path": "docforge.cli.mkdocs_utils.load_nav_spec",
"signature": "<bound method Alias.signature of Alias('load_nav_spec', 'docforge.nav.load_nav_spec')>", "signature": "<bound method Alias.signature of Alias('load_nav_spec', 'docforge.nav.load_nav_spec')>",
"docstring": "Load a navigation specification file.\n\nThis helper function reads a YAML navigation file and constructs a\ncorresponding ``NavSpec`` instance.\n\nArgs:\n path: Path to the navigation specification file.\n\nReturns:\n A ``NavSpec`` instance representing the parsed specification.\n\nRaises:\n FileNotFoundError: If the specification file does not exist.\n ValueError: If the YAML structure is invalid." "docstring": "Utility function to load a NavSpec from a file.\n\nArgs:\n path: Path to the navigation specification file.\n\nReturns:\n A loaded NavSpec instance."
}, },
"resolve_nav": { "resolve_nav": {
"name": "resolve_nav", "name": "resolve_nav",
"kind": "function", "kind": "function",
"path": "docforge.cli.mkdocs_utils.resolve_nav", "path": "docforge.cli.mkdocs_utils.resolve_nav",
"signature": "<bound method Alias.signature of Alias('resolve_nav', 'docforge.nav.resolve_nav')>", "signature": "<bound method Alias.signature of Alias('resolve_nav', 'docforge.nav.resolve_nav')>",
"docstring": "Resolve a navigation specification against the filesystem.\n\nThe function expands glob patterns defined in a ``NavSpec`` and verifies\nthat referenced documentation files exist within the documentation root.\n\nArgs:\n spec: Navigation specification describing documentation layout.\n docs_root: Root directory containing documentation Markdown files.\n\nReturns:\n A ``ResolvedNav`` instance containing validated navigation paths.\n\nRaises:\n FileNotFoundError: If the documentation root does not exist or a\n navigation pattern does not match any files." "docstring": "Create a ResolvedNav by processing a NavSpec against the filesystem.\nThis expands globs and validates the existence of referenced files.\n\nArgs:\n spec: The navigation specification to resolve.\n docs_root: The root directory for documentation files.\n\nReturns:\n A ResolvedNav instance.\n\nRaises:\n FileNotFoundError: If a pattern doesn't match any files or the docs_root doesn't exist."
}, },
"MkDocsNavEmitter": { "MkDocsNavEmitter": {
"name": "MkDocsNavEmitter", "name": "MkDocsNavEmitter",
"kind": "class", "kind": "class",
"path": "docforge.cli.mkdocs_utils.MkDocsNavEmitter", "path": "docforge.cli.mkdocs_utils.MkDocsNavEmitter",
"signature": "<bound method Alias.signature of Alias('MkDocsNavEmitter', 'docforge.nav.MkDocsNavEmitter')>", "signature": "<bound method Alias.signature of Alias('MkDocsNavEmitter', 'docforge.nav.MkDocsNavEmitter')>",
"docstring": "Emit MkDocs navigation structures from resolved navigation data.\n\nThe emitter transforms a ``ResolvedNav`` object into the YAML-compatible\nlist structure expected by the MkDocs ``nav`` configuration field.", "docstring": "Emitter responsible for transforming a ResolvedNav into an MkDocs-compatible\nnavigation structure.",
"members": { "members": {
"emit": { "emit": {
"name": "emit", "name": "emit",
"kind": "function", "kind": "function",
"path": "docforge.cli.mkdocs_utils.MkDocsNavEmitter.emit", "path": "docforge.cli.mkdocs_utils.MkDocsNavEmitter.emit",
"signature": "<bound method Alias.signature of Alias('emit', 'docforge.nav.mkdocs.MkDocsNavEmitter.emit')>", "signature": "<bound method Alias.signature of Alias('emit', 'docforge.nav.mkdocs.MkDocsNavEmitter.emit')>",
"docstring": "Generate a navigation structure for ``mkdocs.yml``.\n\nArgs:\n nav: Resolved navigation data describing documentation groups\n and their associated Markdown files.\n\nReturns:\n A list of dictionaries representing the MkDocs navigation layout.\n Each dictionary maps a navigation label to a page or a list of\n pages." "docstring": "Generate a list of navigation entries for mkdocs.yml.\n\nArgs:\n nav: The resolved navigation data.\n\nReturns:\n A list of dictionary mappings representing the MkDocs navigation."
} }
} }
}, },
@@ -653,29 +639,29 @@
"name": "generate_sources", "name": "generate_sources",
"kind": "function", "kind": "function",
"path": "docforge.cli.mkdocs_utils.generate_sources", "path": "docforge.cli.mkdocs_utils.generate_sources",
"signature": "<bound method Function.signature of Function('generate_sources', 16, 59)>", "signature": "<bound method Function.signature of Function('generate_sources', 9, 23)>",
"docstring": "Generate MkDocs Markdown sources for a Python module.\n\nThis function introspects the specified module, builds the internal\ndocumentation model, and renders Markdown documentation files for\nuse with MkDocs.\n\nArgs:\n module (str):\n Python module import path used as the entry point for\n documentation generation.\n\n docs_dir (Path):\n Directory where the generated Markdown files will be written.\n\n project_name (Optional[str]):\n Optional override for the project name used in documentation metadata.\n\n module_is_source (Optional[bool]):\n If True, treat the specified module directory as the project root\n rather than a nested module." "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."
}, },
"generate_config": { "generate_config": {
"name": "generate_config", "name": "generate_config",
"kind": "function", "kind": "function",
"path": "docforge.cli.mkdocs_utils.generate_config", "path": "docforge.cli.mkdocs_utils.generate_config",
"signature": "<bound method Function.signature of Function('generate_config', 62, 120)>", "signature": "<bound method Function.signature of Function('generate_config', 25, 59)>",
"docstring": "Generate an `mkdocs.yml` configuration file.\n\nThe configuration is created by combining a template configuration\nwith a navigation structure derived from the docforge navigation\nspecification.\n\nArgs:\n docs_dir (Path):\n Directory containing generated documentation Markdown files.\n\n nav_file (Path):\n Path to the `docforge.nav.yml` navigation specification.\n\n template (Optional[Path]):\n Optional path to a custom MkDocs configuration template. If not\n provided, a built-in template will be used.\n\n out (Path):\n Destination path where the generated `mkdocs.yml` file will be written.\n\n site_name (str):\n Display name for the generated documentation site.\n\nRaises:\n click.FileError:\n If the navigation specification or template file cannot be found." "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": { "build": {
"name": "build", "name": "build",
"kind": "function", "kind": "function",
"path": "docforge.cli.mkdocs_utils.build", "path": "docforge.cli.mkdocs_utils.build",
"signature": "<bound method Function.signature of Function('build', 123, 144)>", "signature": "<bound method Function.signature of Function('build', 61, 74)>",
"docstring": "Build the MkDocs documentation site.\n\nThis function loads the MkDocs configuration and runs the MkDocs\nbuild command to generate the final static documentation site.\n\nArgs:\n mkdocs_yml (Path):\n Path to the `mkdocs.yml` configuration file.\n\nRaises:\n click.ClickException:\n If the configuration file does not exist." "docstring": "Build the documentation site using MkDocs.\n\nArgs:\n mkdocs_yml: Path to the mkdocs.yml configuration file."
}, },
"serve": { "serve": {
"name": "serve", "name": "serve",
"kind": "function", "kind": "function",
"path": "docforge.cli.mkdocs_utils.serve", "path": "docforge.cli.mkdocs_utils.serve",
"signature": "<bound method Function.signature of Function('serve', 147, 166)>", "signature": "<bound method Function.signature of Function('serve', 76, 87)>",
"docstring": "Start an MkDocs development server with live reload.\n\nThe server watches documentation files and automatically reloads\nthe site when changes are detected.\n\nArgs:\n mkdocs_yml (Path):\n Path to the `mkdocs.yml` configuration file.\n\nRaises:\n click.ClickException:\n If the configuration file does not exist." "docstring": "Serve the documentation site with live-reload using MkDocs.\n\nArgs:\n mkdocs_yml: Path to the mkdocs.yml configuration file."
} }
} }
} }

6
mcp_docs/modules/docforge.cli.main.json
View File

@@ -2,7 +2,7 @@
"module": "docforge.cli.main", "module": "docforge.cli.main",
"content": { "content": {
"path": "docforge.cli.main", "path": "docforge.cli.main",
"docstring": "# Summary\n\nCommand-line entry point for the doc-forge CLI.\n\nThis module exposes the executable entry point that initializes the\nClick command group defined in `docforge.cli.commands`.", "docstring": "Main entry point for the doc-forge CLI. This module delegates all command\nexecution to docforge.cli.commands.",
"objects": { "objects": {
"cli": { "cli": {
"name": "cli", "name": "cli",
@@ -15,8 +15,8 @@
"name": "main", "name": "main",
"kind": "function", "kind": "function",
"path": "docforge.cli.main.main", "path": "docforge.cli.main.main",
"signature": "<bound method Function.signature of Function('main', 13, 21)>", "signature": "<bound method Function.signature of Function('main', 7, 11)>",
"docstring": "Run the doc-forge command-line interface.\n\nThis function initializes and executes the Click CLI application.\nIt is used as the console entry point when invoking `doc-forge`\nfrom the command line." "docstring": "CLI Entry point. Boots the click application."
} }
} }
} }

26
mcp_docs/modules/docforge.cli.mcp_utils.json
View File

@@ -2,7 +2,7 @@
"module": "docforge.cli.mcp_utils", "module": "docforge.cli.mcp_utils",
"content": { "content": {
"path": "docforge.cli.mcp_utils", "path": "docforge.cli.mcp_utils",
"docstring": "# Summary\n\nUtilities for working with MCP in the doc-forge CLI.", "docstring": null,
"objects": { "objects": {
"Path": { "Path": {
"name": "Path", "name": "Path",
@@ -23,21 +23,21 @@
"kind": "class", "kind": "class",
"path": "docforge.cli.mcp_utils.GriffeLoader", "path": "docforge.cli.mcp_utils.GriffeLoader",
"signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.loaders.GriffeLoader')>", "signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.loaders.GriffeLoader')>",
"docstring": "Load Python modules using Griffe and convert them into doc-forge models.\n\nThis loader uses the Griffe introspection engine to analyze Python source\ncode and transform the extracted information into `Project`, `Module`,\nand `DocObject` instances used by doc-forge.", "docstring": "Loads Python modules and extracts documentation using the Griffe introspection engine.",
"members": { "members": {
"load_project": { "load_project": {
"name": "load_project", "name": "load_project",
"kind": "function", "kind": "function",
"path": "docforge.cli.mcp_utils.GriffeLoader.load_project", "path": "docforge.cli.mcp_utils.GriffeLoader.load_project",
"signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>", "signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>",
"docstring": "Load multiple modules and assemble them into a Project model.\n\nEach module path is introspected and converted into a `Module`\ninstance. All modules are then aggregated into a single `Project`\nobject.\n\nArgs:\n module_paths (List[str]):\n List of dotted module import paths to load.\n\n project_name (str, optional):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool, optional):\n If True, modules that fail to load will be skipped instead of raising an error.\n\nReturns:\n Project:\n A populated `Project` instance containing the loaded modules.\n\nRaises:\n ValueError:\n If no module paths are provided.\n\n ImportError:\n If a module fails to load and `skip_import_errors` is False." "docstring": "Load multiple modules and combine them into a single Project models.\n\nArgs:\n module_paths: A list of dotted paths to the modules to load.\n project_name: Optional name for the project. Defaults to the first module name.\n skip_import_errors: If True, modules that fail to import will be skipped.\n\nReturns:\n A Project instance containing the loaded modules."
}, },
"load_module": { "load_module": {
"name": "load_module", "name": "load_module",
"kind": "function", "kind": "function",
"path": "docforge.cli.mcp_utils.GriffeLoader.load_module", "path": "docforge.cli.mcp_utils.GriffeLoader.load_module",
"signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>", "signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>",
"docstring": "Load and convert a single Python module.\n\nThe module is introspected using Griffe and then transformed into\na doc-forge `Module` model.\n\nArgs:\n path (str):\n Dotted import path of the module.\n\nReturns:\n Module:\n A populated `Module` instance." "docstring": "Load a single module and convert its introspection data into the docforge models.\n\nArgs:\n path: The dotted path of the module to load.\n\nReturns:\n A Module instance."
} }
} }
}, },
@@ -46,14 +46,14 @@
"kind": "function", "kind": "function",
"path": "docforge.cli.mcp_utils.discover_module_paths", "path": "docforge.cli.mcp_utils.discover_module_paths",
"signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.loaders.discover_module_paths')>", "signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.loaders.discover_module_paths')>",
"docstring": "Discover Python modules within a package directory.\n\nThe function scans the filesystem for `.py` files inside the specified\npackage and converts them into dotted module import paths.\n\nDiscovery rules:\n\n- Directories containing `__init__.py` are treated as packages.\n- Each `.py` file is treated as a module.\n- Results are returned as dotted import paths.\n\nArgs:\n module_name (str):\n Top-level package name to discover modules from.\n\n project_root (Path, optional):\n Root directory used to resolve module paths. If not provided, the\n current working directory is used.\n\nReturns:\n List[str]:\n A sorted list of unique dotted module import paths.\n\nRaises:\n FileNotFoundError:\n If the specified package directory does not exist." "docstring": "Discover all Python modules under a package via filesystem traversal.\n\nRules:\n- Directory with __init__.py is treated as a package.\n- Any .py file is treated as a module.\n- All paths are converted to dotted module paths.\n\nArgs:\n module_name: The name of the package to discover.\n project_root: The root directory of the project. Defaults to current working directory.\n\nReturns:\n A sorted list of dotted module paths."
}, },
"MCPRenderer": { "MCPRenderer": {
"name": "MCPRenderer", "name": "MCPRenderer",
"kind": "class", "kind": "class",
"path": "docforge.cli.mcp_utils.MCPRenderer", "path": "docforge.cli.mcp_utils.MCPRenderer",
"signature": "<bound method Alias.signature of Alias('MCPRenderer', 'docforge.renderers.MCPRenderer')>", "signature": "<bound method Alias.signature of Alias('MCPRenderer', 'docforge.renderers.MCPRenderer')>",
"docstring": "Renderer that generates MCP-compatible documentation resources.\n\nThis renderer converts doc-forge project models into structured JSON\nresources suitable for consumption by systems implementing the Model\nContext Protocol (MCP).", "docstring": "Renderer that emits MCP-native JSON resources from docforge models.",
"members": { "members": {
"name": { "name": {
"name": "name", "name": "name",
@@ -67,7 +67,7 @@
"kind": "function", "kind": "function",
"path": "docforge.cli.mcp_utils.MCPRenderer.generate_sources", "path": "docforge.cli.mcp_utils.MCPRenderer.generate_sources",
"signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mcp_renderer.MCPRenderer.generate_sources')>", "signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mcp_renderer.MCPRenderer.generate_sources')>",
"docstring": "Generate MCP documentation resources for a project.\n\nThe renderer serializes each module into a JSON resource and produces\nsupporting metadata files such as `nav.json` and `index.json`.\n\nArgs:\n project (Project):\n Documentation project model to render.\n\n out_dir (Path):\n Directory where MCP resources will be written." "docstring": "Generate MCP-compatible JSON resources and navigation for the project.\n\nArgs:\n project: The project model to render.\n out_dir: Target directory for the generated JSON files."
} }
} }
}, },
@@ -76,7 +76,7 @@
"kind": "class", "kind": "class",
"path": "docforge.cli.mcp_utils.MCPServer", "path": "docforge.cli.mcp_utils.MCPServer",
"signature": "<bound method Alias.signature of Alias('MCPServer', 'docforge.servers.MCPServer')>", "signature": "<bound method Alias.signature of Alias('MCPServer', 'docforge.servers.MCPServer')>",
"docstring": "MCP server for serving a pre-generated documentation bundle.\n\nThe server exposes documentation resources and diagnostic tools through\nMCP endpoints backed by JSON files generated by the MCP renderer.", "docstring": "MCP server for serving a pre-built MCP documentation bundle.",
"members": { "members": {
"mcp_root": { "mcp_root": {
"name": "mcp_root", "name": "mcp_root",
@@ -97,7 +97,7 @@
"kind": "function", "kind": "function",
"path": "docforge.cli.mcp_utils.MCPServer.run", "path": "docforge.cli.mcp_utils.MCPServer.run",
"signature": "<bound method Alias.signature of Alias('run', 'docforge.servers.mcp_server.MCPServer.run')>", "signature": "<bound method Alias.signature of Alias('run', 'docforge.servers.mcp_server.MCPServer.run')>",
"docstring": "Start the MCP server.\n\nArgs:\n transport (Literal[\"stdio\", \"sse\", \"streamable-http\"]):\n Transport mechanism used by the MCP server. Supported options\n include `stdio`, `sse`, and `streamable-http`." "docstring": "Start the MCP server.\n\nArgs:\n transport: MCP transport (default: streamable-http)"
} }
} }
}, },
@@ -105,15 +105,15 @@
"name": "generate_resources", "name": "generate_resources",
"kind": "function", "kind": "function",
"path": "docforge.cli.mcp_utils.generate_resources", "path": "docforge.cli.mcp_utils.generate_resources",
"signature": "<bound method Function.signature of Function('generate_resources', 14, 40)>", "signature": "<bound method Function.signature of Function('generate_resources', 7, 21)>",
"docstring": "Generate MCP documentation resources from a Python module.\n\nThe function performs project introspection, builds the internal\ndocumentation model, and renders MCP-compatible JSON resources\nto the specified output directory.\n\nArgs:\n module (str):\n Python module import path used as the entry point for\n documentation generation.\n\n project_name (Optional[str]):\n Optional override for the project name used in generated\n documentation metadata.\n\n out_dir (Path):\n Directory where MCP resources (index.json, nav.json, and module data)\n will be written." "docstring": "Generate MCP-compatible documentation resources.\n\nArgs:\n module: The dotted path of the primary module to document.\n project_name: Optional override for the project name.\n out_dir: Directory where the MCP JSON resources and nav will be written."
}, },
"serve": { "serve": {
"name": "serve", "name": "serve",
"kind": "function", "kind": "function",
"path": "docforge.cli.mcp_utils.serve", "path": "docforge.cli.mcp_utils.serve",
"signature": "<bound method Function.signature of Function('serve', 43, 80)>", "signature": "<bound method Function.signature of Function('serve', 23, 47)>",
"docstring": "Start an MCP server for a pre-generated documentation bundle.\n\nThe server exposes documentation resources such as project metadata,\nnavigation structure, and module documentation through MCP endpoints.\n\nArgs:\n module (str):\n Python module import path used to identify the served\n documentation instance.\n\n mcp_root (Path):\n Path to the directory containing the MCP documentation\n bundle (index.json, nav.json, and modules/).\n\nRaises:\n click.ClickException:\n If the MCP documentation bundle is missing required files or directories." "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/."
} }
} }
} }

45
mcp_docs/modules/docforge.cli.mkdocs_utils.json
View File

@@ -2,7 +2,7 @@
"module": "docforge.cli.mkdocs_utils", "module": "docforge.cli.mkdocs_utils",
"content": { "content": {
"path": "docforge.cli.mkdocs_utils", "path": "docforge.cli.mkdocs_utils",
"docstring": "# Summary\n\nUtilities for working with MkDocs in the doc-forge CLI.", "docstring": null,
"objects": { "objects": {
"Path": { "Path": {
"name": "Path", "name": "Path",
@@ -37,21 +37,21 @@
"kind": "class", "kind": "class",
"path": "docforge.cli.mkdocs_utils.GriffeLoader", "path": "docforge.cli.mkdocs_utils.GriffeLoader",
"signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.loaders.GriffeLoader')>", "signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.loaders.GriffeLoader')>",
"docstring": "Load Python modules using Griffe and convert them into doc-forge models.\n\nThis loader uses the Griffe introspection engine to analyze Python source\ncode and transform the extracted information into `Project`, `Module`,\nand `DocObject` instances used by doc-forge.", "docstring": "Loads Python modules and extracts documentation using the Griffe introspection engine.",
"members": { "members": {
"load_project": { "load_project": {
"name": "load_project", "name": "load_project",
"kind": "function", "kind": "function",
"path": "docforge.cli.mkdocs_utils.GriffeLoader.load_project", "path": "docforge.cli.mkdocs_utils.GriffeLoader.load_project",
"signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>", "signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>",
"docstring": "Load multiple modules and assemble them into a Project model.\n\nEach module path is introspected and converted into a `Module`\ninstance. All modules are then aggregated into a single `Project`\nobject.\n\nArgs:\n module_paths (List[str]):\n List of dotted module import paths to load.\n\n project_name (str, optional):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool, optional):\n If True, modules that fail to load will be skipped instead of raising an error.\n\nReturns:\n Project:\n A populated `Project` instance containing the loaded modules.\n\nRaises:\n ValueError:\n If no module paths are provided.\n\n ImportError:\n If a module fails to load and `skip_import_errors` is False." "docstring": "Load multiple modules and combine them into a single Project models.\n\nArgs:\n module_paths: A list of dotted paths to the modules to load.\n project_name: Optional name for the project. Defaults to the first module name.\n skip_import_errors: If True, modules that fail to import will be skipped.\n\nReturns:\n A Project instance containing the loaded modules."
}, },
"load_module": { "load_module": {
"name": "load_module", "name": "load_module",
"kind": "function", "kind": "function",
"path": "docforge.cli.mkdocs_utils.GriffeLoader.load_module", "path": "docforge.cli.mkdocs_utils.GriffeLoader.load_module",
"signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>", "signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>",
"docstring": "Load and convert a single Python module.\n\nThe module is introspected using Griffe and then transformed into\na doc-forge `Module` model.\n\nArgs:\n path (str):\n Dotted import path of the module.\n\nReturns:\n Module:\n A populated `Module` instance." "docstring": "Load a single module and convert its introspection data into the docforge models.\n\nArgs:\n path: The dotted path of the module to load.\n\nReturns:\n A Module instance."
} }
} }
}, },
@@ -60,14 +60,14 @@
"kind": "function", "kind": "function",
"path": "docforge.cli.mkdocs_utils.discover_module_paths", "path": "docforge.cli.mkdocs_utils.discover_module_paths",
"signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.loaders.discover_module_paths')>", "signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.loaders.discover_module_paths')>",
"docstring": "Discover Python modules within a package directory.\n\nThe function scans the filesystem for `.py` files inside the specified\npackage and converts them into dotted module import paths.\n\nDiscovery rules:\n\n- Directories containing `__init__.py` are treated as packages.\n- Each `.py` file is treated as a module.\n- Results are returned as dotted import paths.\n\nArgs:\n module_name (str):\n Top-level package name to discover modules from.\n\n project_root (Path, optional):\n Root directory used to resolve module paths. If not provided, the\n current working directory is used.\n\nReturns:\n List[str]:\n A sorted list of unique dotted module import paths.\n\nRaises:\n FileNotFoundError:\n If the specified package directory does not exist." "docstring": "Discover all Python modules under a package via filesystem traversal.\n\nRules:\n- Directory with __init__.py is treated as a package.\n- Any .py file is treated as a module.\n- All paths are converted to dotted module paths.\n\nArgs:\n module_name: The name of the package to discover.\n project_root: The root directory of the project. Defaults to current working directory.\n\nReturns:\n A sorted list of dotted module paths."
}, },
"MkDocsRenderer": { "MkDocsRenderer": {
"name": "MkDocsRenderer", "name": "MkDocsRenderer",
"kind": "class", "kind": "class",
"path": "docforge.cli.mkdocs_utils.MkDocsRenderer", "path": "docforge.cli.mkdocs_utils.MkDocsRenderer",
"signature": "<bound method Alias.signature of Alias('MkDocsRenderer', 'docforge.renderers.MkDocsRenderer')>", "signature": "<bound method Alias.signature of Alias('MkDocsRenderer', 'docforge.renderers.MkDocsRenderer')>",
"docstring": "Renderer that produces Markdown documentation for MkDocs.\n\nGenerated pages use mkdocstrings directives to reference Python modules,\nallowing MkDocs to render API documentation dynamically.", "docstring": "Renderer that generates Markdown source files formatted for the MkDocs\n'mkdocstrings' plugin.",
"members": { "members": {
"name": { "name": {
"name": "name", "name": "name",
@@ -81,14 +81,7 @@
"kind": "function", "kind": "function",
"path": "docforge.cli.mkdocs_utils.MkDocsRenderer.generate_sources", "path": "docforge.cli.mkdocs_utils.MkDocsRenderer.generate_sources",
"signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources')>", "signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources')>",
"docstring": "Generate Markdown documentation files for a project.\n\nThis method renders a documentation structure from the provided\nproject model and writes the resulting Markdown files to the\nspecified output directory.\n\nArgs:\n project (Project):\n Project model containing modules to document.\n\n out_dir (Path):\n Directory where generated Markdown files will be written.\n\n module_is_source (bool, optional):\n If True, treat the specified module as the documentation root\n rather than nesting it inside a folder." "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."
},
"generate_readme": {
"name": "generate_readme",
"kind": "function",
"path": "docforge.cli.mkdocs_utils.MkDocsRenderer.generate_readme",
"signature": "<bound method Alias.signature of Alias('generate_readme', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_readme')>",
"docstring": "Generate a `README.md` file from the root module docstring.\n\nBehavior:\n\n- If `module_is_source` is True, `README.md` is written to the project\n root directory.\n- If False, README generation is currently not implemented.\n\nArgs:\n project (Project):\n Project model containing documentation metadata.\n\n docs_dir (Path):\n Directory containing generated documentation sources.\n\n module_is_source (bool, optional):\n Whether the module is treated as the project source root."
} }
} }
}, },
@@ -97,28 +90,28 @@
"kind": "function", "kind": "function",
"path": "docforge.cli.mkdocs_utils.load_nav_spec", "path": "docforge.cli.mkdocs_utils.load_nav_spec",
"signature": "<bound method Alias.signature of Alias('load_nav_spec', 'docforge.nav.load_nav_spec')>", "signature": "<bound method Alias.signature of Alias('load_nav_spec', 'docforge.nav.load_nav_spec')>",
"docstring": "Load a navigation specification file.\n\nThis helper function reads a YAML navigation file and constructs a\ncorresponding ``NavSpec`` instance.\n\nArgs:\n path: Path to the navigation specification file.\n\nReturns:\n A ``NavSpec`` instance representing the parsed specification.\n\nRaises:\n FileNotFoundError: If the specification file does not exist.\n ValueError: If the YAML structure is invalid." "docstring": "Utility function to load a NavSpec from a file.\n\nArgs:\n path: Path to the navigation specification file.\n\nReturns:\n A loaded NavSpec instance."
}, },
"resolve_nav": { "resolve_nav": {
"name": "resolve_nav", "name": "resolve_nav",
"kind": "function", "kind": "function",
"path": "docforge.cli.mkdocs_utils.resolve_nav", "path": "docforge.cli.mkdocs_utils.resolve_nav",
"signature": "<bound method Alias.signature of Alias('resolve_nav', 'docforge.nav.resolve_nav')>", "signature": "<bound method Alias.signature of Alias('resolve_nav', 'docforge.nav.resolve_nav')>",
"docstring": "Resolve a navigation specification against the filesystem.\n\nThe function expands glob patterns defined in a ``NavSpec`` and verifies\nthat referenced documentation files exist within the documentation root.\n\nArgs:\n spec: Navigation specification describing documentation layout.\n docs_root: Root directory containing documentation Markdown files.\n\nReturns:\n A ``ResolvedNav`` instance containing validated navigation paths.\n\nRaises:\n FileNotFoundError: If the documentation root does not exist or a\n navigation pattern does not match any files." "docstring": "Create a ResolvedNav by processing a NavSpec against the filesystem.\nThis expands globs and validates the existence of referenced files.\n\nArgs:\n spec: The navigation specification to resolve.\n docs_root: The root directory for documentation files.\n\nReturns:\n A ResolvedNav instance.\n\nRaises:\n FileNotFoundError: If a pattern doesn't match any files or the docs_root doesn't exist."
}, },
"MkDocsNavEmitter": { "MkDocsNavEmitter": {
"name": "MkDocsNavEmitter", "name": "MkDocsNavEmitter",
"kind": "class", "kind": "class",
"path": "docforge.cli.mkdocs_utils.MkDocsNavEmitter", "path": "docforge.cli.mkdocs_utils.MkDocsNavEmitter",
"signature": "<bound method Alias.signature of Alias('MkDocsNavEmitter', 'docforge.nav.MkDocsNavEmitter')>", "signature": "<bound method Alias.signature of Alias('MkDocsNavEmitter', 'docforge.nav.MkDocsNavEmitter')>",
"docstring": "Emit MkDocs navigation structures from resolved navigation data.\n\nThe emitter transforms a ``ResolvedNav`` object into the YAML-compatible\nlist structure expected by the MkDocs ``nav`` configuration field.", "docstring": "Emitter responsible for transforming a ResolvedNav into an MkDocs-compatible\nnavigation structure.",
"members": { "members": {
"emit": { "emit": {
"name": "emit", "name": "emit",
"kind": "function", "kind": "function",
"path": "docforge.cli.mkdocs_utils.MkDocsNavEmitter.emit", "path": "docforge.cli.mkdocs_utils.MkDocsNavEmitter.emit",
"signature": "<bound method Alias.signature of Alias('emit', 'docforge.nav.mkdocs.MkDocsNavEmitter.emit')>", "signature": "<bound method Alias.signature of Alias('emit', 'docforge.nav.mkdocs.MkDocsNavEmitter.emit')>",
"docstring": "Generate a navigation structure for ``mkdocs.yml``.\n\nArgs:\n nav: Resolved navigation data describing documentation groups\n and their associated Markdown files.\n\nReturns:\n A list of dictionaries representing the MkDocs navigation layout.\n Each dictionary maps a navigation label to a page or a list of\n pages." "docstring": "Generate a list of navigation entries for mkdocs.yml.\n\nArgs:\n nav: The resolved navigation data.\n\nReturns:\n A list of dictionary mappings representing the MkDocs navigation."
} }
} }
}, },
@@ -126,29 +119,29 @@
"name": "generate_sources", "name": "generate_sources",
"kind": "function", "kind": "function",
"path": "docforge.cli.mkdocs_utils.generate_sources", "path": "docforge.cli.mkdocs_utils.generate_sources",
"signature": "<bound method Function.signature of Function('generate_sources', 16, 59)>", "signature": "<bound method Function.signature of Function('generate_sources', 9, 23)>",
"docstring": "Generate MkDocs Markdown sources for a Python module.\n\nThis function introspects the specified module, builds the internal\ndocumentation model, and renders Markdown documentation files for\nuse with MkDocs.\n\nArgs:\n module (str):\n Python module import path used as the entry point for\n documentation generation.\n\n docs_dir (Path):\n Directory where the generated Markdown files will be written.\n\n project_name (Optional[str]):\n Optional override for the project name used in documentation metadata.\n\n module_is_source (Optional[bool]):\n If True, treat the specified module directory as the project root\n rather than a nested module." "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."
}, },
"generate_config": { "generate_config": {
"name": "generate_config", "name": "generate_config",
"kind": "function", "kind": "function",
"path": "docforge.cli.mkdocs_utils.generate_config", "path": "docforge.cli.mkdocs_utils.generate_config",
"signature": "<bound method Function.signature of Function('generate_config', 62, 120)>", "signature": "<bound method Function.signature of Function('generate_config', 25, 59)>",
"docstring": "Generate an `mkdocs.yml` configuration file.\n\nThe configuration is created by combining a template configuration\nwith a navigation structure derived from the docforge navigation\nspecification.\n\nArgs:\n docs_dir (Path):\n Directory containing generated documentation Markdown files.\n\n nav_file (Path):\n Path to the `docforge.nav.yml` navigation specification.\n\n template (Optional[Path]):\n Optional path to a custom MkDocs configuration template. If not\n provided, a built-in template will be used.\n\n out (Path):\n Destination path where the generated `mkdocs.yml` file will be written.\n\n site_name (str):\n Display name for the generated documentation site.\n\nRaises:\n click.FileError:\n If the navigation specification or template file cannot be found." "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": { "build": {
"name": "build", "name": "build",
"kind": "function", "kind": "function",
"path": "docforge.cli.mkdocs_utils.build", "path": "docforge.cli.mkdocs_utils.build",
"signature": "<bound method Function.signature of Function('build', 123, 144)>", "signature": "<bound method Function.signature of Function('build', 61, 74)>",
"docstring": "Build the MkDocs documentation site.\n\nThis function loads the MkDocs configuration and runs the MkDocs\nbuild command to generate the final static documentation site.\n\nArgs:\n mkdocs_yml (Path):\n Path to the `mkdocs.yml` configuration file.\n\nRaises:\n click.ClickException:\n If the configuration file does not exist." "docstring": "Build the documentation site using MkDocs.\n\nArgs:\n mkdocs_yml: Path to the mkdocs.yml configuration file."
}, },
"serve": { "serve": {
"name": "serve", "name": "serve",
"kind": "function", "kind": "function",
"path": "docforge.cli.mkdocs_utils.serve", "path": "docforge.cli.mkdocs_utils.serve",
"signature": "<bound method Function.signature of Function('serve', 147, 166)>", "signature": "<bound method Function.signature of Function('serve', 76, 87)>",
"docstring": "Start an MkDocs development server with live reload.\n\nThe server watches documentation files and automatically reloads\nthe site when changes are detected.\n\nArgs:\n mkdocs_yml (Path):\n Path to the `mkdocs.yml` configuration file.\n\nRaises:\n click.ClickException:\n If the configuration file does not exist." "docstring": "Serve the documentation site with live-reload using MkDocs.\n\nArgs:\n mkdocs_yml: Path to the mkdocs.yml configuration file."
} }
} }
} }

588
mcp_docs/modules/docforge.json
View File

File diff suppressed because one or more lines are too long

44
mcp_docs/modules/docforge.loaders.griffe_loader.json
View File

@@ -2,7 +2,7 @@
"module": "docforge.loaders.griffe_loader", "module": "docforge.loaders.griffe_loader",
"content": { "content": {
"path": "docforge.loaders.griffe_loader", "path": "docforge.loaders.griffe_loader",
"docstring": "# Summary\n\nUtilities for loading and introspecting Python modules using Griffe.\n\nThis module provides the `GriffeLoader` class and helper utilities used to\ndiscover Python modules, introspect their structure, and convert the results\ninto doc-forge documentation models.", "docstring": "This module provides the GriffeLoader, which uses the 'griffe' library to\nintrospect Python source code and populate the doc-forge Project models.",
"objects": { "objects": {
"logging": { "logging": {
"name": "logging", "name": "logging",
@@ -65,7 +65,7 @@
"kind": "class", "kind": "class",
"path": "docforge.loaders.griffe_loader.Module", "path": "docforge.loaders.griffe_loader.Module",
"signature": "<bound method Alias.signature of Alias('Module', 'docforge.models.Module')>", "signature": "<bound method Alias.signature of Alias('Module', 'docforge.models.Module')>",
"docstring": "Representation of a documented Python module or package.\n\nA `Module` stores metadata about the module itself and maintains a\ncollection of top-level documentation objects discovered during\nintrospection.\n\nAttributes:\n path (str):\n Dotted import path of the module.\n\n docstring (Optional[str]):\n Module-level documentation string, if present.\n\n members (Dict[str, DocObject]):\n Mapping of object names to their corresponding `DocObject` representations.", "docstring": "Represents a documented Python module or package.\n\nAttributes:\n path: Dotted import path of the module.\n docstring: Module-level docstring content.\n members: Dictionary mapping object names to their DocObject representations.",
"members": { "members": {
"path": { "path": {
"name": "path", "name": "path",
@@ -93,21 +93,21 @@
"kind": "function", "kind": "function",
"path": "docforge.loaders.griffe_loader.Module.add_object", "path": "docforge.loaders.griffe_loader.Module.add_object",
"signature": "<bound method Alias.signature of Alias('add_object', 'docforge.models.module.Module.add_object')>", "signature": "<bound method Alias.signature of Alias('add_object', 'docforge.models.module.Module.add_object')>",
"docstring": "Add a documented object to the module.\n\nArgs:\n obj (DocObject):\n Documentation object to register as a top-level member of the module." "docstring": "Add a documented object to the module.\n\nArgs:\n obj: The object to add."
}, },
"get_object": { "get_object": {
"name": "get_object", "name": "get_object",
"kind": "function", "kind": "function",
"path": "docforge.loaders.griffe_loader.Module.get_object", "path": "docforge.loaders.griffe_loader.Module.get_object",
"signature": "<bound method Alias.signature of Alias('get_object', 'docforge.models.module.Module.get_object')>", "signature": "<bound method Alias.signature of Alias('get_object', 'docforge.models.module.Module.get_object')>",
"docstring": "Retrieve a documented object by name.\n\nArgs:\n name (str):\n Name of the object to retrieve.\n\nReturns:\n DocObject:\n The corresponding `DocObject` instance.\n\nRaises:\n KeyError:\n If no object with the given name exists." "docstring": "Retrieve a member object by name.\n\nArgs:\n name: The name of the object.\n\nReturns:\n The requested DocObject."
}, },
"get_all_objects": { "get_all_objects": {
"name": "get_all_objects", "name": "get_all_objects",
"kind": "function", "kind": "function",
"path": "docforge.loaders.griffe_loader.Module.get_all_objects", "path": "docforge.loaders.griffe_loader.Module.get_all_objects",
"signature": "<bound method Alias.signature of Alias('get_all_objects', 'docforge.models.module.Module.get_all_objects')>", "signature": "<bound method Alias.signature of Alias('get_all_objects', 'docforge.models.module.Module.get_all_objects')>",
"docstring": "Return all top-level documentation objects in the module.\n\nReturns:\n Iterable[DocObject]:\n An iterable of `DocObject` instances representing the module's public members." "docstring": "Get all top-level objects in the module.\n\nReturns:\n An iterable of DocObject instances."
} }
} }
}, },
@@ -116,7 +116,7 @@
"kind": "class", "kind": "class",
"path": "docforge.loaders.griffe_loader.Project", "path": "docforge.loaders.griffe_loader.Project",
"signature": "<bound method Alias.signature of Alias('Project', 'docforge.models.Project')>", "signature": "<bound method Alias.signature of Alias('Project', 'docforge.models.Project')>",
"docstring": "Representation of a documentation project.\n\nA `Project` serves as the root container for all modules discovered during\nintrospection. Each module is stored by its dotted import path.\n\nAttributes:\n name (str):\n Name of the project.\n\n modules (Dict[str, Module]):\n Mapping of module paths to `Module` instances.", "docstring": "Represents a documentation project, serving as a container for modules.\n\nAttributes:\n name: Name of the project.\n modules: Dictionary mapping module paths to Module instances.",
"members": { "members": {
"name": { "name": {
"name": "name", "name": "name",
@@ -137,28 +137,28 @@
"kind": "function", "kind": "function",
"path": "docforge.loaders.griffe_loader.Project.add_module", "path": "docforge.loaders.griffe_loader.Project.add_module",
"signature": "<bound method Alias.signature of Alias('add_module', 'docforge.models.project.Project.add_module')>", "signature": "<bound method Alias.signature of Alias('add_module', 'docforge.models.project.Project.add_module')>",
"docstring": "Register a module in the project.\n\nArgs:\n module (Module):\n Module instance to add to the project." "docstring": "Add a module to the project.\n\nArgs:\n module: The module to add."
}, },
"get_module": { "get_module": {
"name": "get_module", "name": "get_module",
"kind": "function", "kind": "function",
"path": "docforge.loaders.griffe_loader.Project.get_module", "path": "docforge.loaders.griffe_loader.Project.get_module",
"signature": "<bound method Alias.signature of Alias('get_module', 'docforge.models.project.Project.get_module')>", "signature": "<bound method Alias.signature of Alias('get_module', 'docforge.models.project.Project.get_module')>",
"docstring": "Retrieve a module by its dotted path.\n\nArgs:\n path (str):\n Fully qualified dotted module path (for example `pkg.module`).\n\nReturns:\n Module:\n The corresponding `Module` instance.\n\nRaises:\n KeyError:\n If the module does not exist in the project." "docstring": "Retrieve a module by its dotted path.\n\nArgs:\n path: The dotted path of the module (e.g., 'pkg.mod').\n\nReturns:\n The requested Module."
}, },
"get_all_modules": { "get_all_modules": {
"name": "get_all_modules", "name": "get_all_modules",
"kind": "function", "kind": "function",
"path": "docforge.loaders.griffe_loader.Project.get_all_modules", "path": "docforge.loaders.griffe_loader.Project.get_all_modules",
"signature": "<bound method Alias.signature of Alias('get_all_modules', 'docforge.models.project.Project.get_all_modules')>", "signature": "<bound method Alias.signature of Alias('get_all_modules', 'docforge.models.project.Project.get_all_modules')>",
"docstring": "Return all modules contained in the project.\n\nReturns:\n Iterable[Module]:\n An iterable of `Module` instances." "docstring": "Get all modules in the project.\n\nReturns:\n An iterable of Module objects."
}, },
"get_module_list": { "get_module_list": {
"name": "get_module_list", "name": "get_module_list",
"kind": "function", "kind": "function",
"path": "docforge.loaders.griffe_loader.Project.get_module_list", "path": "docforge.loaders.griffe_loader.Project.get_module_list",
"signature": "<bound method Alias.signature of Alias('get_module_list', 'docforge.models.project.Project.get_module_list')>", "signature": "<bound method Alias.signature of Alias('get_module_list', 'docforge.models.project.Project.get_module_list')>",
"docstring": "Return the list of module import paths.\n\nReturns:\n list[str]:\n A list containing the dotted paths of all modules in the project." "docstring": "Get the list of all module dotted paths.\n\nReturns:\n A list of module paths."
} }
} }
}, },
@@ -167,7 +167,7 @@
"kind": "class", "kind": "class",
"path": "docforge.loaders.griffe_loader.DocObject", "path": "docforge.loaders.griffe_loader.DocObject",
"signature": "<bound method Alias.signature of Alias('DocObject', 'docforge.models.DocObject')>", "signature": "<bound method Alias.signature of Alias('DocObject', 'docforge.models.DocObject')>",
"docstring": "Representation of a documented Python object.\n\nA `DocObject` models a single Python entity discovered during\nintrospection. Objects may contain nested members, allowing the structure\nof modules, classes, and other containers to be represented recursively.\n\nAttributes:\n name (str):\n Local name of the object.\n\n kind (str):\n Type of object (for example `class`, `function`, `method`, or `attribute`).\n\n path (str):\n Fully qualified dotted path to the object.\n\n signature (Optional[str]):\n Callable signature if the object represents a callable.\n\n docstring (Optional[str]):\n Raw docstring text extracted from the source code.\n\n members (Dict[str, DocObject]):\n Mapping of member names to child `DocObject` instances.", "docstring": "Represents a documented Python object (class, function, method, etc.).\n\nAttributes:\n name: Local name of the object.\n kind: Type of object (e.g., 'class', 'function', 'attribute').\n path: Full dotted import path to the object.\n signature: Callable signature, if applicable.\n docstring: Raw docstring content extracted from the source.\n members: Dictionary mapping member names to their DocObject representations.",
"members": { "members": {
"name": { "name": {
"name": "name", "name": "name",
@@ -216,21 +216,21 @@
"kind": "function", "kind": "function",
"path": "docforge.loaders.griffe_loader.DocObject.add_member", "path": "docforge.loaders.griffe_loader.DocObject.add_member",
"signature": "<bound method Alias.signature of Alias('add_member', 'docforge.models.object.DocObject.add_member')>", "signature": "<bound method Alias.signature of Alias('add_member', 'docforge.models.object.DocObject.add_member')>",
"docstring": "Add a child documentation object.\n\nThis is typically used when attaching methods to classes or\nnested objects to their parent containers.\n\nArgs:\n obj: Documentation object to add as a member." "docstring": "Add a child member to this object (e.g., a method to a class).\n\nArgs:\n obj: The child DocObject to add."
}, },
"get_member": { "get_member": {
"name": "get_member", "name": "get_member",
"kind": "function", "kind": "function",
"path": "docforge.loaders.griffe_loader.DocObject.get_member", "path": "docforge.loaders.griffe_loader.DocObject.get_member",
"signature": "<bound method Alias.signature of Alias('get_member', 'docforge.models.object.DocObject.get_member')>", "signature": "<bound method Alias.signature of Alias('get_member', 'docforge.models.object.DocObject.get_member')>",
"docstring": "Retrieve a member object by name.\n\nArgs:\n name (str):\n Name of the member to retrieve.\n\nReturns:\n DocObject:\n The corresponding `DocObject` instance.\n\nRaises:\n KeyError:\n If the member does not exist." "docstring": "Retrieve a child member by name.\n\nArgs:\n name: The name of the member.\n\nReturns:\n The requested DocObject."
}, },
"get_all_members": { "get_all_members": {
"name": "get_all_members", "name": "get_all_members",
"kind": "function", "kind": "function",
"path": "docforge.loaders.griffe_loader.DocObject.get_all_members", "path": "docforge.loaders.griffe_loader.DocObject.get_all_members",
"signature": "<bound method Alias.signature of Alias('get_all_members', 'docforge.models.object.DocObject.get_all_members')>", "signature": "<bound method Alias.signature of Alias('get_all_members', 'docforge.models.object.DocObject.get_all_members')>",
"docstring": "Return all child members of the object.\n\nReturns:\n Iterable[DocObject]:\n An iterable of `DocObject` instances representing nested members." "docstring": "Get all members of this object.\n\nReturns:\n An iterable of child DocObject instances."
} }
} }
}, },
@@ -245,29 +245,29 @@
"name": "discover_module_paths", "name": "discover_module_paths",
"kind": "function", "kind": "function",
"path": "docforge.loaders.griffe_loader.discover_module_paths", "path": "docforge.loaders.griffe_loader.discover_module_paths",
"signature": "<bound method Function.signature of Function('discover_module_paths', 28, 80)>", "signature": "<bound method Function.signature of Function('discover_module_paths', 23, 62)>",
"docstring": "Discover Python modules within a package directory.\n\nThe function scans the filesystem for `.py` files inside the specified\npackage and converts them into dotted module import paths.\n\nDiscovery rules:\n\n- Directories containing `__init__.py` are treated as packages.\n- Each `.py` file is treated as a module.\n- Results are returned as dotted import paths.\n\nArgs:\n module_name (str):\n Top-level package name to discover modules from.\n\n project_root (Path, optional):\n Root directory used to resolve module paths. If not provided, the\n current working directory is used.\n\nReturns:\n List[str]:\n A sorted list of unique dotted module import paths.\n\nRaises:\n FileNotFoundError:\n If the specified package directory does not exist." "docstring": "Discover all Python modules under a package via filesystem traversal.\n\nRules:\n- Directory with __init__.py is treated as a package.\n- Any .py file is treated as a module.\n- All paths are converted to dotted module paths.\n\nArgs:\n module_name: The name of the package to discover.\n project_root: The root directory of the project. Defaults to current working directory.\n\nReturns:\n A sorted list of dotted module paths."
}, },
"GriffeLoader": { "GriffeLoader": {
"name": "GriffeLoader", "name": "GriffeLoader",
"kind": "class", "kind": "class",
"path": "docforge.loaders.griffe_loader.GriffeLoader", "path": "docforge.loaders.griffe_loader.GriffeLoader",
"signature": "<bound method Class.signature of Class('GriffeLoader', 83, 287)>", "signature": "<bound method Class.signature of Class('GriffeLoader', 65, 224)>",
"docstring": "Load Python modules using Griffe and convert them into doc-forge models.\n\nThis loader uses the Griffe introspection engine to analyze Python source\ncode and transform the extracted information into `Project`, `Module`,\nand `DocObject` instances used by doc-forge.", "docstring": "Loads Python modules and extracts documentation using the Griffe introspection engine.",
"members": { "members": {
"load_project": { "load_project": {
"name": "load_project", "name": "load_project",
"kind": "function", "kind": "function",
"path": "docforge.loaders.griffe_loader.GriffeLoader.load_project", "path": "docforge.loaders.griffe_loader.GriffeLoader.load_project",
"signature": "<bound method Function.signature of Function('load_project', 104, 158)>", "signature": "<bound method Function.signature of Function('load_project', 79, 115)>",
"docstring": "Load multiple modules and assemble them into a Project model.\n\nEach module path is introspected and converted into a `Module`\ninstance. All modules are then aggregated into a single `Project`\nobject.\n\nArgs:\n module_paths (List[str]):\n List of dotted module import paths to load.\n\n project_name (str, optional):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool, optional):\n If True, modules that fail to load will be skipped instead of raising an error.\n\nReturns:\n Project:\n A populated `Project` instance containing the loaded modules.\n\nRaises:\n ValueError:\n If no module paths are provided.\n\n ImportError:\n If a module fails to load and `skip_import_errors` is False." "docstring": "Load multiple modules and combine them into a single Project models.\n\nArgs:\n module_paths: A list of dotted paths to the modules to load.\n project_name: Optional name for the project. Defaults to the first module name.\n skip_import_errors: If True, modules that fail to import will be skipped.\n\nReturns:\n A Project instance containing the loaded modules."
}, },
"load_module": { "load_module": {
"name": "load_module", "name": "load_module",
"kind": "function", "kind": "function",
"path": "docforge.loaders.griffe_loader.GriffeLoader.load_module", "path": "docforge.loaders.griffe_loader.GriffeLoader.load_module",
"signature": "<bound method Function.signature of Function('load_module', 160, 178)>", "signature": "<bound method Function.signature of Function('load_module', 117, 130)>",
"docstring": "Load and convert a single Python module.\n\nThe module is introspected using Griffe and then transformed into\na doc-forge `Module` model.\n\nArgs:\n path (str):\n Dotted import path of the module.\n\nReturns:\n Module:\n A populated `Module` instance." "docstring": "Load a single module and convert its introspection data into the docforge models.\n\nArgs:\n path: The dotted path of the module to load.\n\nReturns:\n A Module instance."
} }
} }
} }

54
mcp_docs/modules/docforge.loaders.json
View File

@@ -2,28 +2,28 @@
"module": "docforge.loaders", "module": "docforge.loaders",
"content": { "content": {
"path": "docforge.loaders", "path": "docforge.loaders",
"docstring": "# Summary\n\nLoader layer for doc-forge.\n\nThe `docforge.loaders` package is responsible for discovering Python modules\nand extracting documentation data using static analysis.\n\n---\n\n# Overview\n\nThis layer converts Python source code into an intermediate documentation\nmodel used by doc-forge. It performs module discovery, introspection, and\ninitial filtering before the data is passed to the core documentation models.\n\nCore capabilities include:\n\n- **Module discovery** – Locate Python modules and packages within a project.\n- **Static introspection** – Parse docstrings, signatures, and object\n hierarchies using the `griffe` library without executing the code.\n- **Public API filtering** – Exclude private members (names prefixed with\n `_`) to produce clean public documentation structures.\n\n---", "docstring": "# Loader Layer\n\nThe `docforge.loaders` package is responsible for discovering Python source files\nand extracting their documentation using static analysis.\n\n## Core Features\n\n- **Discovery**: Automatically find all modules and packages in a project\n directory.\n- **Introspection**: Uses `griffe` to parse docstrings, signatures, and\n hierarchical relationships without executing the code.\n- **Filtering**: Automatically excludes private members (prefixed with `_`) to\n ensure clean public documentation.",
"objects": { "objects": {
"GriffeLoader": { "GriffeLoader": {
"name": "GriffeLoader", "name": "GriffeLoader",
"kind": "class", "kind": "class",
"path": "docforge.loaders.GriffeLoader", "path": "docforge.loaders.GriffeLoader",
"signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.loaders.griffe_loader.GriffeLoader')>", "signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.loaders.griffe_loader.GriffeLoader')>",
"docstring": "Load Python modules using Griffe and convert them into doc-forge models.\n\nThis loader uses the Griffe introspection engine to analyze Python source\ncode and transform the extracted information into `Project`, `Module`,\nand `DocObject` instances used by doc-forge.", "docstring": "Loads Python modules and extracts documentation using the Griffe introspection engine.",
"members": { "members": {
"load_project": { "load_project": {
"name": "load_project", "name": "load_project",
"kind": "function", "kind": "function",
"path": "docforge.loaders.GriffeLoader.load_project", "path": "docforge.loaders.GriffeLoader.load_project",
"signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>", "signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>",
"docstring": "Load multiple modules and assemble them into a Project model.\n\nEach module path is introspected and converted into a `Module`\ninstance. All modules are then aggregated into a single `Project`\nobject.\n\nArgs:\n module_paths (List[str]):\n List of dotted module import paths to load.\n\n project_name (str, optional):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool, optional):\n If True, modules that fail to load will be skipped instead of raising an error.\n\nReturns:\n Project:\n A populated `Project` instance containing the loaded modules.\n\nRaises:\n ValueError:\n If no module paths are provided.\n\n ImportError:\n If a module fails to load and `skip_import_errors` is False." "docstring": "Load multiple modules and combine them into a single Project models.\n\nArgs:\n module_paths: A list of dotted paths to the modules to load.\n project_name: Optional name for the project. Defaults to the first module name.\n skip_import_errors: If True, modules that fail to import will be skipped.\n\nReturns:\n A Project instance containing the loaded modules."
}, },
"load_module": { "load_module": {
"name": "load_module", "name": "load_module",
"kind": "function", "kind": "function",
"path": "docforge.loaders.GriffeLoader.load_module", "path": "docforge.loaders.GriffeLoader.load_module",
"signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>", "signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>",
"docstring": "Load and convert a single Python module.\n\nThe module is introspected using Griffe and then transformed into\na doc-forge `Module` model.\n\nArgs:\n path (str):\n Dotted import path of the module.\n\nReturns:\n Module:\n A populated `Module` instance." "docstring": "Load a single module and convert its introspection data into the docforge models.\n\nArgs:\n path: The dotted path of the module to load.\n\nReturns:\n A Module instance."
} }
} }
}, },
@@ -32,14 +32,14 @@
"kind": "function", "kind": "function",
"path": "docforge.loaders.discover_module_paths", "path": "docforge.loaders.discover_module_paths",
"signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.loaders.griffe_loader.discover_module_paths')>", "signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.loaders.griffe_loader.discover_module_paths')>",
"docstring": "Discover Python modules within a package directory.\n\nThe function scans the filesystem for `.py` files inside the specified\npackage and converts them into dotted module import paths.\n\nDiscovery rules:\n\n- Directories containing `__init__.py` are treated as packages.\n- Each `.py` file is treated as a module.\n- Results are returned as dotted import paths.\n\nArgs:\n module_name (str):\n Top-level package name to discover modules from.\n\n project_root (Path, optional):\n Root directory used to resolve module paths. If not provided, the\n current working directory is used.\n\nReturns:\n List[str]:\n A sorted list of unique dotted module import paths.\n\nRaises:\n FileNotFoundError:\n If the specified package directory does not exist." "docstring": "Discover all Python modules under a package via filesystem traversal.\n\nRules:\n- Directory with __init__.py is treated as a package.\n- Any .py file is treated as a module.\n- All paths are converted to dotted module paths.\n\nArgs:\n module_name: The name of the package to discover.\n project_root: The root directory of the project. Defaults to current working directory.\n\nReturns:\n A sorted list of dotted module paths."
}, },
"griffe_loader": { "griffe_loader": {
"name": "griffe_loader", "name": "griffe_loader",
"kind": "module", "kind": "module",
"path": "docforge.loaders.griffe_loader", "path": "docforge.loaders.griffe_loader",
"signature": null, "signature": null,
"docstring": "# Summary\n\nUtilities for loading and introspecting Python modules using Griffe.\n\nThis module provides the `GriffeLoader` class and helper utilities used to\ndiscover Python modules, introspect their structure, and convert the results\ninto doc-forge documentation models.", "docstring": "This module provides the GriffeLoader, which uses the 'griffe' library to\nintrospect Python source code and populate the doc-forge Project models.",
"members": { "members": {
"logging": { "logging": {
"name": "logging", "name": "logging",
@@ -102,7 +102,7 @@
"kind": "class", "kind": "class",
"path": "docforge.loaders.griffe_loader.Module", "path": "docforge.loaders.griffe_loader.Module",
"signature": "<bound method Alias.signature of Alias('Module', 'docforge.models.Module')>", "signature": "<bound method Alias.signature of Alias('Module', 'docforge.models.Module')>",
"docstring": "Representation of a documented Python module or package.\n\nA `Module` stores metadata about the module itself and maintains a\ncollection of top-level documentation objects discovered during\nintrospection.\n\nAttributes:\n path (str):\n Dotted import path of the module.\n\n docstring (Optional[str]):\n Module-level documentation string, if present.\n\n members (Dict[str, DocObject]):\n Mapping of object names to their corresponding `DocObject` representations.", "docstring": "Represents a documented Python module or package.\n\nAttributes:\n path: Dotted import path of the module.\n docstring: Module-level docstring content.\n members: Dictionary mapping object names to their DocObject representations.",
"members": { "members": {
"path": { "path": {
"name": "path", "name": "path",
@@ -130,21 +130,21 @@
"kind": "function", "kind": "function",
"path": "docforge.loaders.griffe_loader.Module.add_object", "path": "docforge.loaders.griffe_loader.Module.add_object",
"signature": "<bound method Alias.signature of Alias('add_object', 'docforge.models.module.Module.add_object')>", "signature": "<bound method Alias.signature of Alias('add_object', 'docforge.models.module.Module.add_object')>",
"docstring": "Add a documented object to the module.\n\nArgs:\n obj (DocObject):\n Documentation object to register as a top-level member of the module." "docstring": "Add a documented object to the module.\n\nArgs:\n obj: The object to add."
}, },
"get_object": { "get_object": {
"name": "get_object", "name": "get_object",
"kind": "function", "kind": "function",
"path": "docforge.loaders.griffe_loader.Module.get_object", "path": "docforge.loaders.griffe_loader.Module.get_object",
"signature": "<bound method Alias.signature of Alias('get_object', 'docforge.models.module.Module.get_object')>", "signature": "<bound method Alias.signature of Alias('get_object', 'docforge.models.module.Module.get_object')>",
"docstring": "Retrieve a documented object by name.\n\nArgs:\n name (str):\n Name of the object to retrieve.\n\nReturns:\n DocObject:\n The corresponding `DocObject` instance.\n\nRaises:\n KeyError:\n If no object with the given name exists." "docstring": "Retrieve a member object by name.\n\nArgs:\n name: The name of the object.\n\nReturns:\n The requested DocObject."
}, },
"get_all_objects": { "get_all_objects": {
"name": "get_all_objects", "name": "get_all_objects",
"kind": "function", "kind": "function",
"path": "docforge.loaders.griffe_loader.Module.get_all_objects", "path": "docforge.loaders.griffe_loader.Module.get_all_objects",
"signature": "<bound method Alias.signature of Alias('get_all_objects', 'docforge.models.module.Module.get_all_objects')>", "signature": "<bound method Alias.signature of Alias('get_all_objects', 'docforge.models.module.Module.get_all_objects')>",
"docstring": "Return all top-level documentation objects in the module.\n\nReturns:\n Iterable[DocObject]:\n An iterable of `DocObject` instances representing the module's public members." "docstring": "Get all top-level objects in the module.\n\nReturns:\n An iterable of DocObject instances."
} }
} }
}, },
@@ -153,7 +153,7 @@
"kind": "class", "kind": "class",
"path": "docforge.loaders.griffe_loader.Project", "path": "docforge.loaders.griffe_loader.Project",
"signature": "<bound method Alias.signature of Alias('Project', 'docforge.models.Project')>", "signature": "<bound method Alias.signature of Alias('Project', 'docforge.models.Project')>",
"docstring": "Representation of a documentation project.\n\nA `Project` serves as the root container for all modules discovered during\nintrospection. Each module is stored by its dotted import path.\n\nAttributes:\n name (str):\n Name of the project.\n\n modules (Dict[str, Module]):\n Mapping of module paths to `Module` instances.", "docstring": "Represents a documentation project, serving as a container for modules.\n\nAttributes:\n name: Name of the project.\n modules: Dictionary mapping module paths to Module instances.",
"members": { "members": {
"name": { "name": {
"name": "name", "name": "name",
@@ -174,28 +174,28 @@
"kind": "function", "kind": "function",
"path": "docforge.loaders.griffe_loader.Project.add_module", "path": "docforge.loaders.griffe_loader.Project.add_module",
"signature": "<bound method Alias.signature of Alias('add_module', 'docforge.models.project.Project.add_module')>", "signature": "<bound method Alias.signature of Alias('add_module', 'docforge.models.project.Project.add_module')>",
"docstring": "Register a module in the project.\n\nArgs:\n module (Module):\n Module instance to add to the project." "docstring": "Add a module to the project.\n\nArgs:\n module: The module to add."
}, },
"get_module": { "get_module": {
"name": "get_module", "name": "get_module",
"kind": "function", "kind": "function",
"path": "docforge.loaders.griffe_loader.Project.get_module", "path": "docforge.loaders.griffe_loader.Project.get_module",
"signature": "<bound method Alias.signature of Alias('get_module', 'docforge.models.project.Project.get_module')>", "signature": "<bound method Alias.signature of Alias('get_module', 'docforge.models.project.Project.get_module')>",
"docstring": "Retrieve a module by its dotted path.\n\nArgs:\n path (str):\n Fully qualified dotted module path (for example `pkg.module`).\n\nReturns:\n Module:\n The corresponding `Module` instance.\n\nRaises:\n KeyError:\n If the module does not exist in the project." "docstring": "Retrieve a module by its dotted path.\n\nArgs:\n path: The dotted path of the module (e.g., 'pkg.mod').\n\nReturns:\n The requested Module."
}, },
"get_all_modules": { "get_all_modules": {
"name": "get_all_modules", "name": "get_all_modules",
"kind": "function", "kind": "function",
"path": "docforge.loaders.griffe_loader.Project.get_all_modules", "path": "docforge.loaders.griffe_loader.Project.get_all_modules",
"signature": "<bound method Alias.signature of Alias('get_all_modules', 'docforge.models.project.Project.get_all_modules')>", "signature": "<bound method Alias.signature of Alias('get_all_modules', 'docforge.models.project.Project.get_all_modules')>",
"docstring": "Return all modules contained in the project.\n\nReturns:\n Iterable[Module]:\n An iterable of `Module` instances." "docstring": "Get all modules in the project.\n\nReturns:\n An iterable of Module objects."
}, },
"get_module_list": { "get_module_list": {
"name": "get_module_list", "name": "get_module_list",
"kind": "function", "kind": "function",
"path": "docforge.loaders.griffe_loader.Project.get_module_list", "path": "docforge.loaders.griffe_loader.Project.get_module_list",
"signature": "<bound method Alias.signature of Alias('get_module_list', 'docforge.models.project.Project.get_module_list')>", "signature": "<bound method Alias.signature of Alias('get_module_list', 'docforge.models.project.Project.get_module_list')>",
"docstring": "Return the list of module import paths.\n\nReturns:\n list[str]:\n A list containing the dotted paths of all modules in the project." "docstring": "Get the list of all module dotted paths.\n\nReturns:\n A list of module paths."
} }
} }
}, },
@@ -204,7 +204,7 @@
"kind": "class", "kind": "class",
"path": "docforge.loaders.griffe_loader.DocObject", "path": "docforge.loaders.griffe_loader.DocObject",
"signature": "<bound method Alias.signature of Alias('DocObject', 'docforge.models.DocObject')>", "signature": "<bound method Alias.signature of Alias('DocObject', 'docforge.models.DocObject')>",
"docstring": "Representation of a documented Python object.\n\nA `DocObject` models a single Python entity discovered during\nintrospection. Objects may contain nested members, allowing the structure\nof modules, classes, and other containers to be represented recursively.\n\nAttributes:\n name (str):\n Local name of the object.\n\n kind (str):\n Type of object (for example `class`, `function`, `method`, or `attribute`).\n\n path (str):\n Fully qualified dotted path to the object.\n\n signature (Optional[str]):\n Callable signature if the object represents a callable.\n\n docstring (Optional[str]):\n Raw docstring text extracted from the source code.\n\n members (Dict[str, DocObject]):\n Mapping of member names to child `DocObject` instances.", "docstring": "Represents a documented Python object (class, function, method, etc.).\n\nAttributes:\n name: Local name of the object.\n kind: Type of object (e.g., 'class', 'function', 'attribute').\n path: Full dotted import path to the object.\n signature: Callable signature, if applicable.\n docstring: Raw docstring content extracted from the source.\n members: Dictionary mapping member names to their DocObject representations.",
"members": { "members": {
"name": { "name": {
"name": "name", "name": "name",
@@ -253,21 +253,21 @@
"kind": "function", "kind": "function",
"path": "docforge.loaders.griffe_loader.DocObject.add_member", "path": "docforge.loaders.griffe_loader.DocObject.add_member",
"signature": "<bound method Alias.signature of Alias('add_member', 'docforge.models.object.DocObject.add_member')>", "signature": "<bound method Alias.signature of Alias('add_member', 'docforge.models.object.DocObject.add_member')>",
"docstring": "Add a child documentation object.\n\nThis is typically used when attaching methods to classes or\nnested objects to their parent containers.\n\nArgs:\n obj: Documentation object to add as a member." "docstring": "Add a child member to this object (e.g., a method to a class).\n\nArgs:\n obj: The child DocObject to add."
}, },
"get_member": { "get_member": {
"name": "get_member", "name": "get_member",
"kind": "function", "kind": "function",
"path": "docforge.loaders.griffe_loader.DocObject.get_member", "path": "docforge.loaders.griffe_loader.DocObject.get_member",
"signature": "<bound method Alias.signature of Alias('get_member', 'docforge.models.object.DocObject.get_member')>", "signature": "<bound method Alias.signature of Alias('get_member', 'docforge.models.object.DocObject.get_member')>",
"docstring": "Retrieve a member object by name.\n\nArgs:\n name (str):\n Name of the member to retrieve.\n\nReturns:\n DocObject:\n The corresponding `DocObject` instance.\n\nRaises:\n KeyError:\n If the member does not exist." "docstring": "Retrieve a child member by name.\n\nArgs:\n name: The name of the member.\n\nReturns:\n The requested DocObject."
}, },
"get_all_members": { "get_all_members": {
"name": "get_all_members", "name": "get_all_members",
"kind": "function", "kind": "function",
"path": "docforge.loaders.griffe_loader.DocObject.get_all_members", "path": "docforge.loaders.griffe_loader.DocObject.get_all_members",
"signature": "<bound method Alias.signature of Alias('get_all_members', 'docforge.models.object.DocObject.get_all_members')>", "signature": "<bound method Alias.signature of Alias('get_all_members', 'docforge.models.object.DocObject.get_all_members')>",
"docstring": "Return all child members of the object.\n\nReturns:\n Iterable[DocObject]:\n An iterable of `DocObject` instances representing nested members." "docstring": "Get all members of this object.\n\nReturns:\n An iterable of child DocObject instances."
} }
} }
}, },
@@ -282,29 +282,29 @@
"name": "discover_module_paths", "name": "discover_module_paths",
"kind": "function", "kind": "function",
"path": "docforge.loaders.griffe_loader.discover_module_paths", "path": "docforge.loaders.griffe_loader.discover_module_paths",
"signature": "<bound method Function.signature of Function('discover_module_paths', 28, 80)>", "signature": "<bound method Function.signature of Function('discover_module_paths', 23, 62)>",
"docstring": "Discover Python modules within a package directory.\n\nThe function scans the filesystem for `.py` files inside the specified\npackage and converts them into dotted module import paths.\n\nDiscovery rules:\n\n- Directories containing `__init__.py` are treated as packages.\n- Each `.py` file is treated as a module.\n- Results are returned as dotted import paths.\n\nArgs:\n module_name (str):\n Top-level package name to discover modules from.\n\n project_root (Path, optional):\n Root directory used to resolve module paths. If not provided, the\n current working directory is used.\n\nReturns:\n List[str]:\n A sorted list of unique dotted module import paths.\n\nRaises:\n FileNotFoundError:\n If the specified package directory does not exist." "docstring": "Discover all Python modules under a package via filesystem traversal.\n\nRules:\n- Directory with __init__.py is treated as a package.\n- Any .py file is treated as a module.\n- All paths are converted to dotted module paths.\n\nArgs:\n module_name: The name of the package to discover.\n project_root: The root directory of the project. Defaults to current working directory.\n\nReturns:\n A sorted list of dotted module paths."
}, },
"GriffeLoader": { "GriffeLoader": {
"name": "GriffeLoader", "name": "GriffeLoader",
"kind": "class", "kind": "class",
"path": "docforge.loaders.griffe_loader.GriffeLoader", "path": "docforge.loaders.griffe_loader.GriffeLoader",
"signature": "<bound method Class.signature of Class('GriffeLoader', 83, 287)>", "signature": "<bound method Class.signature of Class('GriffeLoader', 65, 224)>",
"docstring": "Load Python modules using Griffe and convert them into doc-forge models.\n\nThis loader uses the Griffe introspection engine to analyze Python source\ncode and transform the extracted information into `Project`, `Module`,\nand `DocObject` instances used by doc-forge.", "docstring": "Loads Python modules and extracts documentation using the Griffe introspection engine.",
"members": { "members": {
"load_project": { "load_project": {
"name": "load_project", "name": "load_project",
"kind": "function", "kind": "function",
"path": "docforge.loaders.griffe_loader.GriffeLoader.load_project", "path": "docforge.loaders.griffe_loader.GriffeLoader.load_project",
"signature": "<bound method Function.signature of Function('load_project', 104, 158)>", "signature": "<bound method Function.signature of Function('load_project', 79, 115)>",
"docstring": "Load multiple modules and assemble them into a Project model.\n\nEach module path is introspected and converted into a `Module`\ninstance. All modules are then aggregated into a single `Project`\nobject.\n\nArgs:\n module_paths (List[str]):\n List of dotted module import paths to load.\n\n project_name (str, optional):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool, optional):\n If True, modules that fail to load will be skipped instead of raising an error.\n\nReturns:\n Project:\n A populated `Project` instance containing the loaded modules.\n\nRaises:\n ValueError:\n If no module paths are provided.\n\n ImportError:\n If a module fails to load and `skip_import_errors` is False." "docstring": "Load multiple modules and combine them into a single Project models.\n\nArgs:\n module_paths: A list of dotted paths to the modules to load.\n project_name: Optional name for the project. Defaults to the first module name.\n skip_import_errors: If True, modules that fail to import will be skipped.\n\nReturns:\n A Project instance containing the loaded modules."
}, },
"load_module": { "load_module": {
"name": "load_module", "name": "load_module",
"kind": "function", "kind": "function",
"path": "docforge.loaders.griffe_loader.GriffeLoader.load_module", "path": "docforge.loaders.griffe_loader.GriffeLoader.load_module",
"signature": "<bound method Function.signature of Function('load_module', 160, 178)>", "signature": "<bound method Function.signature of Function('load_module', 117, 130)>",
"docstring": "Load and convert a single Python module.\n\nThe module is introspected using Griffe and then transformed into\na doc-forge `Module` model.\n\nArgs:\n path (str):\n Dotted import path of the module.\n\nReturns:\n Module:\n A populated `Module` instance." "docstring": "Load a single module and convert its introspection data into the docforge models.\n\nArgs:\n path: The dotted path of the module to load.\n\nReturns:\n A Module instance."
} }
} }
} }

102
mcp_docs/modules/docforge.models.json
View File

@@ -2,14 +2,14 @@
"module": "docforge.models", "module": "docforge.models",
"content": { "content": {
"path": "docforge.models", "path": "docforge.models",
"docstring": "# Summary\n\nModel layer for doc-forge.\n\nThe `docforge.models` package defines the core data structures used to\nrepresent Python source code as a structured documentation model.\n\n---\n\n# Overview\n\nThe model layer forms the central intermediate representation used throughout\ndoc-forge. Python modules and objects discovered during introspection are\nconverted into a hierarchy of documentation models that can later be rendered\ninto different documentation formats.\n\nKey components:\n\n- **Project** – Root container representing an entire documented codebase.\n- **Module** – Representation of a Python module or package containing\n documented members.\n- **DocObject** – Recursive structure representing Python objects such as\n classes, functions, methods, and attributes.\n\nThese models are intentionally **renderer-agnostic**, allowing the same\ndocumentation structure to be transformed into multiple output formats\n(e.g., MkDocs, MCP, or other renderers).\n\n---", "docstring": "# Model Layer\n\nThe `docforge.models` package provides the core data structures used to represent\nPython source code in a documentation-focused hierarchy.\n\n## Key Components\n\n- **Project**: The root container for all documented modules.\n- **Module**: Represents a Python module or package, containing members.\n- **DocObject**: A recursive structure for classes, functions, and attributes.\n\nThese classes are designed to be renderer-agnostic, allowing the same internal\nrepresentation to be transformed into various output formats (currently MkDocs).",
"objects": { "objects": {
"Project": { "Project": {
"name": "Project", "name": "Project",
"kind": "class", "kind": "class",
"path": "docforge.models.Project", "path": "docforge.models.Project",
"signature": "<bound method Alias.signature of Alias('Project', 'docforge.models.project.Project')>", "signature": "<bound method Alias.signature of Alias('Project', 'docforge.models.project.Project')>",
"docstring": "Representation of a documentation project.\n\nA `Project` serves as the root container for all modules discovered during\nintrospection. Each module is stored by its dotted import path.\n\nAttributes:\n name (str):\n Name of the project.\n\n modules (Dict[str, Module]):\n Mapping of module paths to `Module` instances.", "docstring": "Represents a documentation project, serving as a container for modules.\n\nAttributes:\n name: Name of the project.\n modules: Dictionary mapping module paths to Module instances.",
"members": { "members": {
"name": { "name": {
"name": "name", "name": "name",
@@ -30,28 +30,28 @@
"kind": "function", "kind": "function",
"path": "docforge.models.Project.add_module", "path": "docforge.models.Project.add_module",
"signature": "<bound method Alias.signature of Alias('add_module', 'docforge.models.project.Project.add_module')>", "signature": "<bound method Alias.signature of Alias('add_module', 'docforge.models.project.Project.add_module')>",
"docstring": "Register a module in the project.\n\nArgs:\n module (Module):\n Module instance to add to the project." "docstring": "Add a module to the project.\n\nArgs:\n module: The module to add."
}, },
"get_module": { "get_module": {
"name": "get_module", "name": "get_module",
"kind": "function", "kind": "function",
"path": "docforge.models.Project.get_module", "path": "docforge.models.Project.get_module",
"signature": "<bound method Alias.signature of Alias('get_module', 'docforge.models.project.Project.get_module')>", "signature": "<bound method Alias.signature of Alias('get_module', 'docforge.models.project.Project.get_module')>",
"docstring": "Retrieve a module by its dotted path.\n\nArgs:\n path (str):\n Fully qualified dotted module path (for example `pkg.module`).\n\nReturns:\n Module:\n The corresponding `Module` instance.\n\nRaises:\n KeyError:\n If the module does not exist in the project." "docstring": "Retrieve a module by its dotted path.\n\nArgs:\n path: The dotted path of the module (e.g., 'pkg.mod').\n\nReturns:\n The requested Module."
}, },
"get_all_modules": { "get_all_modules": {
"name": "get_all_modules", "name": "get_all_modules",
"kind": "function", "kind": "function",
"path": "docforge.models.Project.get_all_modules", "path": "docforge.models.Project.get_all_modules",
"signature": "<bound method Alias.signature of Alias('get_all_modules', 'docforge.models.project.Project.get_all_modules')>", "signature": "<bound method Alias.signature of Alias('get_all_modules', 'docforge.models.project.Project.get_all_modules')>",
"docstring": "Return all modules contained in the project.\n\nReturns:\n Iterable[Module]:\n An iterable of `Module` instances." "docstring": "Get all modules in the project.\n\nReturns:\n An iterable of Module objects."
}, },
"get_module_list": { "get_module_list": {
"name": "get_module_list", "name": "get_module_list",
"kind": "function", "kind": "function",
"path": "docforge.models.Project.get_module_list", "path": "docforge.models.Project.get_module_list",
"signature": "<bound method Alias.signature of Alias('get_module_list', 'docforge.models.project.Project.get_module_list')>", "signature": "<bound method Alias.signature of Alias('get_module_list', 'docforge.models.project.Project.get_module_list')>",
"docstring": "Return the list of module import paths.\n\nReturns:\n list[str]:\n A list containing the dotted paths of all modules in the project." "docstring": "Get the list of all module dotted paths.\n\nReturns:\n A list of module paths."
} }
} }
}, },
@@ -60,7 +60,7 @@
"kind": "class", "kind": "class",
"path": "docforge.models.Module", "path": "docforge.models.Module",
"signature": "<bound method Alias.signature of Alias('Module', 'docforge.models.module.Module')>", "signature": "<bound method Alias.signature of Alias('Module', 'docforge.models.module.Module')>",
"docstring": "Representation of a documented Python module or package.\n\nA `Module` stores metadata about the module itself and maintains a\ncollection of top-level documentation objects discovered during\nintrospection.\n\nAttributes:\n path (str):\n Dotted import path of the module.\n\n docstring (Optional[str]):\n Module-level documentation string, if present.\n\n members (Dict[str, DocObject]):\n Mapping of object names to their corresponding `DocObject` representations.", "docstring": "Represents a documented Python module or package.\n\nAttributes:\n path: Dotted import path of the module.\n docstring: Module-level docstring content.\n members: Dictionary mapping object names to their DocObject representations.",
"members": { "members": {
"path": { "path": {
"name": "path", "name": "path",
@@ -88,21 +88,21 @@
"kind": "function", "kind": "function",
"path": "docforge.models.Module.add_object", "path": "docforge.models.Module.add_object",
"signature": "<bound method Alias.signature of Alias('add_object', 'docforge.models.module.Module.add_object')>", "signature": "<bound method Alias.signature of Alias('add_object', 'docforge.models.module.Module.add_object')>",
"docstring": "Add a documented object to the module.\n\nArgs:\n obj (DocObject):\n Documentation object to register as a top-level member of the module." "docstring": "Add a documented object to the module.\n\nArgs:\n obj: The object to add."
}, },
"get_object": { "get_object": {
"name": "get_object", "name": "get_object",
"kind": "function", "kind": "function",
"path": "docforge.models.Module.get_object", "path": "docforge.models.Module.get_object",
"signature": "<bound method Alias.signature of Alias('get_object', 'docforge.models.module.Module.get_object')>", "signature": "<bound method Alias.signature of Alias('get_object', 'docforge.models.module.Module.get_object')>",
"docstring": "Retrieve a documented object by name.\n\nArgs:\n name (str):\n Name of the object to retrieve.\n\nReturns:\n DocObject:\n The corresponding `DocObject` instance.\n\nRaises:\n KeyError:\n If no object with the given name exists." "docstring": "Retrieve a member object by name.\n\nArgs:\n name: The name of the object.\n\nReturns:\n The requested DocObject."
}, },
"get_all_objects": { "get_all_objects": {
"name": "get_all_objects", "name": "get_all_objects",
"kind": "function", "kind": "function",
"path": "docforge.models.Module.get_all_objects", "path": "docforge.models.Module.get_all_objects",
"signature": "<bound method Alias.signature of Alias('get_all_objects', 'docforge.models.module.Module.get_all_objects')>", "signature": "<bound method Alias.signature of Alias('get_all_objects', 'docforge.models.module.Module.get_all_objects')>",
"docstring": "Return all top-level documentation objects in the module.\n\nReturns:\n Iterable[DocObject]:\n An iterable of `DocObject` instances representing the module's public members." "docstring": "Get all top-level objects in the module.\n\nReturns:\n An iterable of DocObject instances."
} }
} }
}, },
@@ -111,7 +111,7 @@
"kind": "class", "kind": "class",
"path": "docforge.models.DocObject", "path": "docforge.models.DocObject",
"signature": "<bound method Alias.signature of Alias('DocObject', 'docforge.models.object.DocObject')>", "signature": "<bound method Alias.signature of Alias('DocObject', 'docforge.models.object.DocObject')>",
"docstring": "Representation of a documented Python object.\n\nA `DocObject` models a single Python entity discovered during\nintrospection. Objects may contain nested members, allowing the structure\nof modules, classes, and other containers to be represented recursively.\n\nAttributes:\n name (str):\n Local name of the object.\n\n kind (str):\n Type of object (for example `class`, `function`, `method`, or `attribute`).\n\n path (str):\n Fully qualified dotted path to the object.\n\n signature (Optional[str]):\n Callable signature if the object represents a callable.\n\n docstring (Optional[str]):\n Raw docstring text extracted from the source code.\n\n members (Dict[str, DocObject]):\n Mapping of member names to child `DocObject` instances.", "docstring": "Represents a documented Python object (class, function, method, etc.).\n\nAttributes:\n name: Local name of the object.\n kind: Type of object (e.g., 'class', 'function', 'attribute').\n path: Full dotted import path to the object.\n signature: Callable signature, if applicable.\n docstring: Raw docstring content extracted from the source.\n members: Dictionary mapping member names to their DocObject representations.",
"members": { "members": {
"name": { "name": {
"name": "name", "name": "name",
@@ -160,21 +160,21 @@
"kind": "function", "kind": "function",
"path": "docforge.models.DocObject.add_member", "path": "docforge.models.DocObject.add_member",
"signature": "<bound method Alias.signature of Alias('add_member', 'docforge.models.object.DocObject.add_member')>", "signature": "<bound method Alias.signature of Alias('add_member', 'docforge.models.object.DocObject.add_member')>",
"docstring": "Add a child documentation object.\n\nThis is typically used when attaching methods to classes or\nnested objects to their parent containers.\n\nArgs:\n obj: Documentation object to add as a member." "docstring": "Add a child member to this object (e.g., a method to a class).\n\nArgs:\n obj: The child DocObject to add."
}, },
"get_member": { "get_member": {
"name": "get_member", "name": "get_member",
"kind": "function", "kind": "function",
"path": "docforge.models.DocObject.get_member", "path": "docforge.models.DocObject.get_member",
"signature": "<bound method Alias.signature of Alias('get_member', 'docforge.models.object.DocObject.get_member')>", "signature": "<bound method Alias.signature of Alias('get_member', 'docforge.models.object.DocObject.get_member')>",
"docstring": "Retrieve a member object by name.\n\nArgs:\n name (str):\n Name of the member to retrieve.\n\nReturns:\n DocObject:\n The corresponding `DocObject` instance.\n\nRaises:\n KeyError:\n If the member does not exist." "docstring": "Retrieve a child member by name.\n\nArgs:\n name: The name of the member.\n\nReturns:\n The requested DocObject."
}, },
"get_all_members": { "get_all_members": {
"name": "get_all_members", "name": "get_all_members",
"kind": "function", "kind": "function",
"path": "docforge.models.DocObject.get_all_members", "path": "docforge.models.DocObject.get_all_members",
"signature": "<bound method Alias.signature of Alias('get_all_members', 'docforge.models.object.DocObject.get_all_members')>", "signature": "<bound method Alias.signature of Alias('get_all_members', 'docforge.models.object.DocObject.get_all_members')>",
"docstring": "Return all child members of the object.\n\nReturns:\n Iterable[DocObject]:\n An iterable of `DocObject` instances representing nested members." "docstring": "Get all members of this object.\n\nReturns:\n An iterable of child DocObject instances."
} }
} }
}, },
@@ -183,7 +183,7 @@
"kind": "module", "kind": "module",
"path": "docforge.models.module", "path": "docforge.models.module",
"signature": null, "signature": null,
"docstring": "# Summary\n\nDocumentation model representing a Python module or package.\n\nThis module defines the `Module` class used in the doc-forge documentation\nmodel. A `Module` acts as a container for top-level documented objects\n(classes, functions, variables, and other members) discovered during\nintrospection.", "docstring": "This module defines the Module class, which represents a Python module or package\nin the doc-forge documentation models. It acts as a container for top-level\ndocumented objects.",
"members": { "members": {
"Dict": { "Dict": {
"name": "Dict", "name": "Dict",
@@ -211,7 +211,7 @@
"kind": "class", "kind": "class",
"path": "docforge.models.module.DocObject", "path": "docforge.models.module.DocObject",
"signature": "<bound method Alias.signature of Alias('DocObject', 'docforge.models.object.DocObject')>", "signature": "<bound method Alias.signature of Alias('DocObject', 'docforge.models.object.DocObject')>",
"docstring": "Representation of a documented Python object.\n\nA `DocObject` models a single Python entity discovered during\nintrospection. Objects may contain nested members, allowing the structure\nof modules, classes, and other containers to be represented recursively.\n\nAttributes:\n name (str):\n Local name of the object.\n\n kind (str):\n Type of object (for example `class`, `function`, `method`, or `attribute`).\n\n path (str):\n Fully qualified dotted path to the object.\n\n signature (Optional[str]):\n Callable signature if the object represents a callable.\n\n docstring (Optional[str]):\n Raw docstring text extracted from the source code.\n\n members (Dict[str, DocObject]):\n Mapping of member names to child `DocObject` instances.", "docstring": "Represents a documented Python object (class, function, method, etc.).\n\nAttributes:\n name: Local name of the object.\n kind: Type of object (e.g., 'class', 'function', 'attribute').\n path: Full dotted import path to the object.\n signature: Callable signature, if applicable.\n docstring: Raw docstring content extracted from the source.\n members: Dictionary mapping member names to their DocObject representations.",
"members": { "members": {
"name": { "name": {
"name": "name", "name": "name",
@@ -260,21 +260,21 @@
"kind": "function", "kind": "function",
"path": "docforge.models.module.DocObject.add_member", "path": "docforge.models.module.DocObject.add_member",
"signature": "<bound method Alias.signature of Alias('add_member', 'docforge.models.object.DocObject.add_member')>", "signature": "<bound method Alias.signature of Alias('add_member', 'docforge.models.object.DocObject.add_member')>",
"docstring": "Add a child documentation object.\n\nThis is typically used when attaching methods to classes or\nnested objects to their parent containers.\n\nArgs:\n obj: Documentation object to add as a member." "docstring": "Add a child member to this object (e.g., a method to a class).\n\nArgs:\n obj: The child DocObject to add."
}, },
"get_member": { "get_member": {
"name": "get_member", "name": "get_member",
"kind": "function", "kind": "function",
"path": "docforge.models.module.DocObject.get_member", "path": "docforge.models.module.DocObject.get_member",
"signature": "<bound method Alias.signature of Alias('get_member', 'docforge.models.object.DocObject.get_member')>", "signature": "<bound method Alias.signature of Alias('get_member', 'docforge.models.object.DocObject.get_member')>",
"docstring": "Retrieve a member object by name.\n\nArgs:\n name (str):\n Name of the member to retrieve.\n\nReturns:\n DocObject:\n The corresponding `DocObject` instance.\n\nRaises:\n KeyError:\n If the member does not exist." "docstring": "Retrieve a child member by name.\n\nArgs:\n name: The name of the member.\n\nReturns:\n The requested DocObject."
}, },
"get_all_members": { "get_all_members": {
"name": "get_all_members", "name": "get_all_members",
"kind": "function", "kind": "function",
"path": "docforge.models.module.DocObject.get_all_members", "path": "docforge.models.module.DocObject.get_all_members",
"signature": "<bound method Alias.signature of Alias('get_all_members', 'docforge.models.object.DocObject.get_all_members')>", "signature": "<bound method Alias.signature of Alias('get_all_members', 'docforge.models.object.DocObject.get_all_members')>",
"docstring": "Return all child members of the object.\n\nReturns:\n Iterable[DocObject]:\n An iterable of `DocObject` instances representing nested members." "docstring": "Get all members of this object.\n\nReturns:\n An iterable of child DocObject instances."
} }
} }
}, },
@@ -282,8 +282,8 @@
"name": "Module", "name": "Module",
"kind": "class", "kind": "class",
"path": "docforge.models.module.Module", "path": "docforge.models.module.Module",
"signature": "<bound method Class.signature of Class('Module', 17, 91)>", "signature": "<bound method Class.signature of Class('Module', 12, 66)>",
"docstring": "Representation of a documented Python module or package.\n\nA `Module` stores metadata about the module itself and maintains a\ncollection of top-level documentation objects discovered during\nintrospection.\n\nAttributes:\n path (str):\n Dotted import path of the module.\n\n docstring (Optional[str]):\n Module-level documentation string, if present.\n\n members (Dict[str, DocObject]):\n Mapping of object names to their corresponding `DocObject` representations.", "docstring": "Represents a documented Python module or package.\n\nAttributes:\n path: Dotted import path of the module.\n docstring: Module-level docstring content.\n members: Dictionary mapping object names to their DocObject representations.",
"members": { "members": {
"path": { "path": {
"name": "path", "name": "path",
@@ -310,22 +310,22 @@
"name": "add_object", "name": "add_object",
"kind": "function", "kind": "function",
"path": "docforge.models.module.Module.add_object", "path": "docforge.models.module.Module.add_object",
"signature": "<bound method Function.signature of Function('add_object', 55, 63)>", "signature": "<bound method Function.signature of Function('add_object', 38, 45)>",
"docstring": "Add a documented object to the module.\n\nArgs:\n obj (DocObject):\n Documentation object to register as a top-level member of the module." "docstring": "Add a documented object to the module.\n\nArgs:\n obj: The object to add."
}, },
"get_object": { "get_object": {
"name": "get_object", "name": "get_object",
"kind": "function", "kind": "function",
"path": "docforge.models.module.Module.get_object", "path": "docforge.models.module.Module.get_object",
"signature": "<bound method Function.signature of Function('get_object', 65, 81)>", "signature": "<bound method Function.signature of Function('get_object', 47, 57)>",
"docstring": "Retrieve a documented object by name.\n\nArgs:\n name (str):\n Name of the object to retrieve.\n\nReturns:\n DocObject:\n The corresponding `DocObject` instance.\n\nRaises:\n KeyError:\n If no object with the given name exists." "docstring": "Retrieve a member object by name.\n\nArgs:\n name: The name of the object.\n\nReturns:\n The requested DocObject."
}, },
"get_all_objects": { "get_all_objects": {
"name": "get_all_objects", "name": "get_all_objects",
"kind": "function", "kind": "function",
"path": "docforge.models.module.Module.get_all_objects", "path": "docforge.models.module.Module.get_all_objects",
"signature": "<bound method Function.signature of Function('get_all_objects', 83, 91)>", "signature": "<bound method Function.signature of Function('get_all_objects', 59, 66)>",
"docstring": "Return all top-level documentation objects in the module.\n\nReturns:\n Iterable[DocObject]:\n An iterable of `DocObject` instances representing the module's public members." "docstring": "Get all top-level objects in the module.\n\nReturns:\n An iterable of DocObject instances."
} }
} }
} }
@@ -336,7 +336,7 @@
"kind": "module", "kind": "module",
"path": "docforge.models.object", "path": "docforge.models.object",
"signature": null, "signature": null,
"docstring": "# Summary\n\nDocumentation model representing individual Python objects.\n\nThis module defines the `DocObject` class, the fundamental recursive unit of\nthe doc-forge documentation model. Each `DocObject` represents a Python\nentity such as a class, function, method, or attribute, and may contain nested\nmembers that form a hierarchical documentation structure.", "docstring": "This module defines the DocObject class, the fundamental recursive unit of the\ndoc-forge documentation models. A DocObject represents a single Python entity\n(class, function, method, or attribute) and its nested members.",
"members": { "members": {
"Dict": { "Dict": {
"name": "Dict", "name": "Dict",
@@ -363,8 +363,8 @@
"name": "DocObject", "name": "DocObject",
"kind": "class", "kind": "class",
"path": "docforge.models.object.DocObject", "path": "docforge.models.object.DocObject",
"signature": "<bound method Class.signature of Class('DocObject', 15, 115)>", "signature": "<bound method Class.signature of Class('DocObject', 10, 76)>",
"docstring": "Representation of a documented Python object.\n\nA `DocObject` models a single Python entity discovered during\nintrospection. Objects may contain nested members, allowing the structure\nof modules, classes, and other containers to be represented recursively.\n\nAttributes:\n name (str):\n Local name of the object.\n\n kind (str):\n Type of object (for example `class`, `function`, `method`, or `attribute`).\n\n path (str):\n Fully qualified dotted path to the object.\n\n signature (Optional[str]):\n Callable signature if the object represents a callable.\n\n docstring (Optional[str]):\n Raw docstring text extracted from the source code.\n\n members (Dict[str, DocObject]):\n Mapping of member names to child `DocObject` instances.", "docstring": "Represents a documented Python object (class, function, method, etc.).\n\nAttributes:\n name: Local name of the object.\n kind: Type of object (e.g., 'class', 'function', 'attribute').\n path: Full dotted import path to the object.\n signature: Callable signature, if applicable.\n docstring: Raw docstring content extracted from the source.\n members: Dictionary mapping member names to their DocObject representations.",
"members": { "members": {
"name": { "name": {
"name": "name", "name": "name",
@@ -412,22 +412,22 @@
"name": "add_member", "name": "add_member",
"kind": "function", "kind": "function",
"path": "docforge.models.object.DocObject.add_member", "path": "docforge.models.object.DocObject.add_member",
"signature": "<bound method Function.signature of Function('add_member', 77, 87)>", "signature": "<bound method Function.signature of Function('add_member', 48, 55)>",
"docstring": "Add a child documentation object.\n\nThis is typically used when attaching methods to classes or\nnested objects to their parent containers.\n\nArgs:\n obj: Documentation object to add as a member." "docstring": "Add a child member to this object (e.g., a method to a class).\n\nArgs:\n obj: The child DocObject to add."
}, },
"get_member": { "get_member": {
"name": "get_member", "name": "get_member",
"kind": "function", "kind": "function",
"path": "docforge.models.object.DocObject.get_member", "path": "docforge.models.object.DocObject.get_member",
"signature": "<bound method Function.signature of Function('get_member', 89, 105)>", "signature": "<bound method Function.signature of Function('get_member', 57, 67)>",
"docstring": "Retrieve a member object by name.\n\nArgs:\n name (str):\n Name of the member to retrieve.\n\nReturns:\n DocObject:\n The corresponding `DocObject` instance.\n\nRaises:\n KeyError:\n If the member does not exist." "docstring": "Retrieve a child member by name.\n\nArgs:\n name: The name of the member.\n\nReturns:\n The requested DocObject."
}, },
"get_all_members": { "get_all_members": {
"name": "get_all_members", "name": "get_all_members",
"kind": "function", "kind": "function",
"path": "docforge.models.object.DocObject.get_all_members", "path": "docforge.models.object.DocObject.get_all_members",
"signature": "<bound method Function.signature of Function('get_all_members', 107, 115)>", "signature": "<bound method Function.signature of Function('get_all_members', 69, 76)>",
"docstring": "Return all child members of the object.\n\nReturns:\n Iterable[DocObject]:\n An iterable of `DocObject` instances representing nested members." "docstring": "Get all members of this object.\n\nReturns:\n An iterable of child DocObject instances."
} }
} }
} }
@@ -438,7 +438,7 @@
"kind": "module", "kind": "module",
"path": "docforge.models.project", "path": "docforge.models.project",
"signature": null, "signature": null,
"docstring": "# Summary\n\nDocumentation model representing a project.\n\nThis module defines the `Project` class, the top-level container used by\ndoc-forge to represent a documented codebase. A `Project` aggregates multiple\nmodules and provides access to them through a unified interface.", "docstring": "This module defines the Project class, the top-level container for a documented\nproject. It aggregates multiple Module instances into a single named entity.",
"members": { "members": {
"Dict": { "Dict": {
"name": "Dict", "name": "Dict",
@@ -459,7 +459,7 @@
"kind": "class", "kind": "class",
"path": "docforge.models.project.Module", "path": "docforge.models.project.Module",
"signature": "<bound method Alias.signature of Alias('Module', 'docforge.models.module.Module')>", "signature": "<bound method Alias.signature of Alias('Module', 'docforge.models.module.Module')>",
"docstring": "Representation of a documented Python module or package.\n\nA `Module` stores metadata about the module itself and maintains a\ncollection of top-level documentation objects discovered during\nintrospection.\n\nAttributes:\n path (str):\n Dotted import path of the module.\n\n docstring (Optional[str]):\n Module-level documentation string, if present.\n\n members (Dict[str, DocObject]):\n Mapping of object names to their corresponding `DocObject` representations.", "docstring": "Represents a documented Python module or package.\n\nAttributes:\n path: Dotted import path of the module.\n docstring: Module-level docstring content.\n members: Dictionary mapping object names to their DocObject representations.",
"members": { "members": {
"path": { "path": {
"name": "path", "name": "path",
@@ -487,21 +487,21 @@
"kind": "function", "kind": "function",
"path": "docforge.models.project.Module.add_object", "path": "docforge.models.project.Module.add_object",
"signature": "<bound method Alias.signature of Alias('add_object', 'docforge.models.module.Module.add_object')>", "signature": "<bound method Alias.signature of Alias('add_object', 'docforge.models.module.Module.add_object')>",
"docstring": "Add a documented object to the module.\n\nArgs:\n obj (DocObject):\n Documentation object to register as a top-level member of the module." "docstring": "Add a documented object to the module.\n\nArgs:\n obj: The object to add."
}, },
"get_object": { "get_object": {
"name": "get_object", "name": "get_object",
"kind": "function", "kind": "function",
"path": "docforge.models.project.Module.get_object", "path": "docforge.models.project.Module.get_object",
"signature": "<bound method Alias.signature of Alias('get_object', 'docforge.models.module.Module.get_object')>", "signature": "<bound method Alias.signature of Alias('get_object', 'docforge.models.module.Module.get_object')>",
"docstring": "Retrieve a documented object by name.\n\nArgs:\n name (str):\n Name of the object to retrieve.\n\nReturns:\n DocObject:\n The corresponding `DocObject` instance.\n\nRaises:\n KeyError:\n If no object with the given name exists." "docstring": "Retrieve a member object by name.\n\nArgs:\n name: The name of the object.\n\nReturns:\n The requested DocObject."
}, },
"get_all_objects": { "get_all_objects": {
"name": "get_all_objects", "name": "get_all_objects",
"kind": "function", "kind": "function",
"path": "docforge.models.project.Module.get_all_objects", "path": "docforge.models.project.Module.get_all_objects",
"signature": "<bound method Alias.signature of Alias('get_all_objects', 'docforge.models.module.Module.get_all_objects')>", "signature": "<bound method Alias.signature of Alias('get_all_objects', 'docforge.models.module.Module.get_all_objects')>",
"docstring": "Return all top-level documentation objects in the module.\n\nReturns:\n Iterable[DocObject]:\n An iterable of `DocObject` instances representing the module's public members." "docstring": "Get all top-level objects in the module.\n\nReturns:\n An iterable of DocObject instances."
} }
} }
}, },
@@ -509,8 +509,8 @@
"name": "Project", "name": "Project",
"kind": "class", "kind": "class",
"path": "docforge.models.project.Project", "path": "docforge.models.project.Project",
"signature": "<bound method Class.signature of Class('Project', 16, 88)>", "signature": "<bound method Class.signature of Class('Project', 11, 67)>",
"docstring": "Representation of a documentation project.\n\nA `Project` serves as the root container for all modules discovered during\nintrospection. Each module is stored by its dotted import path.\n\nAttributes:\n name (str):\n Name of the project.\n\n modules (Dict[str, Module]):\n Mapping of module paths to `Module` instances.", "docstring": "Represents a documentation project, serving as a container for modules.\n\nAttributes:\n name: Name of the project.\n modules: Dictionary mapping module paths to Module instances.",
"members": { "members": {
"name": { "name": {
"name": "name", "name": "name",
@@ -530,29 +530,29 @@
"name": "add_module", "name": "add_module",
"kind": "function", "kind": "function",
"path": "docforge.models.project.Project.add_module", "path": "docforge.models.project.Project.add_module",
"signature": "<bound method Function.signature of Function('add_module', 42, 50)>", "signature": "<bound method Function.signature of Function('add_module', 30, 37)>",
"docstring": "Register a module in the project.\n\nArgs:\n module (Module):\n Module instance to add to the project." "docstring": "Add a module to the project.\n\nArgs:\n module: The module to add."
}, },
"get_module": { "get_module": {
"name": "get_module", "name": "get_module",
"kind": "function", "kind": "function",
"path": "docforge.models.project.Project.get_module", "path": "docforge.models.project.Project.get_module",
"signature": "<bound method Function.signature of Function('get_module', 52, 68)>", "signature": "<bound method Function.signature of Function('get_module', 39, 49)>",
"docstring": "Retrieve a module by its dotted path.\n\nArgs:\n path (str):\n Fully qualified dotted module path (for example `pkg.module`).\n\nReturns:\n Module:\n The corresponding `Module` instance.\n\nRaises:\n KeyError:\n If the module does not exist in the project." "docstring": "Retrieve a module by its dotted path.\n\nArgs:\n path: The dotted path of the module (e.g., 'pkg.mod').\n\nReturns:\n The requested Module."
}, },
"get_all_modules": { "get_all_modules": {
"name": "get_all_modules", "name": "get_all_modules",
"kind": "function", "kind": "function",
"path": "docforge.models.project.Project.get_all_modules", "path": "docforge.models.project.Project.get_all_modules",
"signature": "<bound method Function.signature of Function('get_all_modules', 70, 78)>", "signature": "<bound method Function.signature of Function('get_all_modules', 51, 58)>",
"docstring": "Return all modules contained in the project.\n\nReturns:\n Iterable[Module]:\n An iterable of `Module` instances." "docstring": "Get all modules in the project.\n\nReturns:\n An iterable of Module objects."
}, },
"get_module_list": { "get_module_list": {
"name": "get_module_list", "name": "get_module_list",
"kind": "function", "kind": "function",
"path": "docforge.models.project.Project.get_module_list", "path": "docforge.models.project.Project.get_module_list",
"signature": "<bound method Function.signature of Function('get_module_list', 80, 88)>", "signature": "<bound method Function.signature of Function('get_module_list', 60, 67)>",
"docstring": "Return the list of module import paths.\n\nReturns:\n list[str]:\n A list containing the dotted paths of all modules in the project." "docstring": "Get the list of all module dotted paths.\n\nReturns:\n A list of module paths."
} }
} }
} }

26
mcp_docs/modules/docforge.models.module.json
View File

@@ -2,7 +2,7 @@
"module": "docforge.models.module", "module": "docforge.models.module",
"content": { "content": {
"path": "docforge.models.module", "path": "docforge.models.module",
"docstring": "# Summary\n\nDocumentation model representing a Python module or package.\n\nThis module defines the `Module` class used in the doc-forge documentation\nmodel. A `Module` acts as a container for top-level documented objects\n(classes, functions, variables, and other members) discovered during\nintrospection.", "docstring": "This module defines the Module class, which represents a Python module or package\nin the doc-forge documentation models. It acts as a container for top-level\ndocumented objects.",
"objects": { "objects": {
"Dict": { "Dict": {
"name": "Dict", "name": "Dict",
@@ -30,7 +30,7 @@
"kind": "class", "kind": "class",
"path": "docforge.models.module.DocObject", "path": "docforge.models.module.DocObject",
"signature": "<bound method Alias.signature of Alias('DocObject', 'docforge.models.object.DocObject')>", "signature": "<bound method Alias.signature of Alias('DocObject', 'docforge.models.object.DocObject')>",
"docstring": "Representation of a documented Python object.\n\nA `DocObject` models a single Python entity discovered during\nintrospection. Objects may contain nested members, allowing the structure\nof modules, classes, and other containers to be represented recursively.\n\nAttributes:\n name (str):\n Local name of the object.\n\n kind (str):\n Type of object (for example `class`, `function`, `method`, or `attribute`).\n\n path (str):\n Fully qualified dotted path to the object.\n\n signature (Optional[str]):\n Callable signature if the object represents a callable.\n\n docstring (Optional[str]):\n Raw docstring text extracted from the source code.\n\n members (Dict[str, DocObject]):\n Mapping of member names to child `DocObject` instances.", "docstring": "Represents a documented Python object (class, function, method, etc.).\n\nAttributes:\n name: Local name of the object.\n kind: Type of object (e.g., 'class', 'function', 'attribute').\n path: Full dotted import path to the object.\n signature: Callable signature, if applicable.\n docstring: Raw docstring content extracted from the source.\n members: Dictionary mapping member names to their DocObject representations.",
"members": { "members": {
"name": { "name": {
"name": "name", "name": "name",
@@ -79,21 +79,21 @@
"kind": "function", "kind": "function",
"path": "docforge.models.module.DocObject.add_member", "path": "docforge.models.module.DocObject.add_member",
"signature": "<bound method Alias.signature of Alias('add_member', 'docforge.models.object.DocObject.add_member')>", "signature": "<bound method Alias.signature of Alias('add_member', 'docforge.models.object.DocObject.add_member')>",
"docstring": "Add a child documentation object.\n\nThis is typically used when attaching methods to classes or\nnested objects to their parent containers.\n\nArgs:\n obj: Documentation object to add as a member." "docstring": "Add a child member to this object (e.g., a method to a class).\n\nArgs:\n obj: The child DocObject to add."
}, },
"get_member": { "get_member": {
"name": "get_member", "name": "get_member",
"kind": "function", "kind": "function",
"path": "docforge.models.module.DocObject.get_member", "path": "docforge.models.module.DocObject.get_member",
"signature": "<bound method Alias.signature of Alias('get_member', 'docforge.models.object.DocObject.get_member')>", "signature": "<bound method Alias.signature of Alias('get_member', 'docforge.models.object.DocObject.get_member')>",
"docstring": "Retrieve a member object by name.\n\nArgs:\n name (str):\n Name of the member to retrieve.\n\nReturns:\n DocObject:\n The corresponding `DocObject` instance.\n\nRaises:\n KeyError:\n If the member does not exist." "docstring": "Retrieve a child member by name.\n\nArgs:\n name: The name of the member.\n\nReturns:\n The requested DocObject."
}, },
"get_all_members": { "get_all_members": {
"name": "get_all_members", "name": "get_all_members",
"kind": "function", "kind": "function",
"path": "docforge.models.module.DocObject.get_all_members", "path": "docforge.models.module.DocObject.get_all_members",
"signature": "<bound method Alias.signature of Alias('get_all_members', 'docforge.models.object.DocObject.get_all_members')>", "signature": "<bound method Alias.signature of Alias('get_all_members', 'docforge.models.object.DocObject.get_all_members')>",
"docstring": "Return all child members of the object.\n\nReturns:\n Iterable[DocObject]:\n An iterable of `DocObject` instances representing nested members." "docstring": "Get all members of this object.\n\nReturns:\n An iterable of child DocObject instances."
} }
} }
}, },
@@ -101,8 +101,8 @@
"name": "Module", "name": "Module",
"kind": "class", "kind": "class",
"path": "docforge.models.module.Module", "path": "docforge.models.module.Module",
"signature": "<bound method Class.signature of Class('Module', 17, 91)>", "signature": "<bound method Class.signature of Class('Module', 12, 66)>",
"docstring": "Representation of a documented Python module or package.\n\nA `Module` stores metadata about the module itself and maintains a\ncollection of top-level documentation objects discovered during\nintrospection.\n\nAttributes:\n path (str):\n Dotted import path of the module.\n\n docstring (Optional[str]):\n Module-level documentation string, if present.\n\n members (Dict[str, DocObject]):\n Mapping of object names to their corresponding `DocObject` representations.", "docstring": "Represents a documented Python module or package.\n\nAttributes:\n path: Dotted import path of the module.\n docstring: Module-level docstring content.\n members: Dictionary mapping object names to their DocObject representations.",
"members": { "members": {
"path": { "path": {
"name": "path", "name": "path",
@@ -129,22 +129,22 @@
"name": "add_object", "name": "add_object",
"kind": "function", "kind": "function",
"path": "docforge.models.module.Module.add_object", "path": "docforge.models.module.Module.add_object",
"signature": "<bound method Function.signature of Function('add_object', 55, 63)>", "signature": "<bound method Function.signature of Function('add_object', 38, 45)>",
"docstring": "Add a documented object to the module.\n\nArgs:\n obj (DocObject):\n Documentation object to register as a top-level member of the module." "docstring": "Add a documented object to the module.\n\nArgs:\n obj: The object to add."
}, },
"get_object": { "get_object": {
"name": "get_object", "name": "get_object",
"kind": "function", "kind": "function",
"path": "docforge.models.module.Module.get_object", "path": "docforge.models.module.Module.get_object",
"signature": "<bound method Function.signature of Function('get_object', 65, 81)>", "signature": "<bound method Function.signature of Function('get_object', 47, 57)>",
"docstring": "Retrieve a documented object by name.\n\nArgs:\n name (str):\n Name of the object to retrieve.\n\nReturns:\n DocObject:\n The corresponding `DocObject` instance.\n\nRaises:\n KeyError:\n If no object with the given name exists." "docstring": "Retrieve a member object by name.\n\nArgs:\n name: The name of the object.\n\nReturns:\n The requested DocObject."
}, },
"get_all_objects": { "get_all_objects": {
"name": "get_all_objects", "name": "get_all_objects",
"kind": "function", "kind": "function",
"path": "docforge.models.module.Module.get_all_objects", "path": "docforge.models.module.Module.get_all_objects",
"signature": "<bound method Function.signature of Function('get_all_objects', 83, 91)>", "signature": "<bound method Function.signature of Function('get_all_objects', 59, 66)>",
"docstring": "Return all top-level documentation objects in the module.\n\nReturns:\n Iterable[DocObject]:\n An iterable of `DocObject` instances representing the module's public members." "docstring": "Get all top-level objects in the module.\n\nReturns:\n An iterable of DocObject instances."
} }
} }
} }

18
mcp_docs/modules/docforge.models.object.json
View File

@@ -2,7 +2,7 @@
"module": "docforge.models.object", "module": "docforge.models.object",
"content": { "content": {
"path": "docforge.models.object", "path": "docforge.models.object",
"docstring": "# Summary\n\nDocumentation model representing individual Python objects.\n\nThis module defines the `DocObject` class, the fundamental recursive unit of\nthe doc-forge documentation model. Each `DocObject` represents a Python\nentity such as a class, function, method, or attribute, and may contain nested\nmembers that form a hierarchical documentation structure.", "docstring": "This module defines the DocObject class, the fundamental recursive unit of the\ndoc-forge documentation models. A DocObject represents a single Python entity\n(class, function, method, or attribute) and its nested members.",
"objects": { "objects": {
"Dict": { "Dict": {
"name": "Dict", "name": "Dict",
@@ -29,8 +29,8 @@
"name": "DocObject", "name": "DocObject",
"kind": "class", "kind": "class",
"path": "docforge.models.object.DocObject", "path": "docforge.models.object.DocObject",
"signature": "<bound method Class.signature of Class('DocObject', 15, 115)>", "signature": "<bound method Class.signature of Class('DocObject', 10, 76)>",
"docstring": "Representation of a documented Python object.\n\nA `DocObject` models a single Python entity discovered during\nintrospection. Objects may contain nested members, allowing the structure\nof modules, classes, and other containers to be represented recursively.\n\nAttributes:\n name (str):\n Local name of the object.\n\n kind (str):\n Type of object (for example `class`, `function`, `method`, or `attribute`).\n\n path (str):\n Fully qualified dotted path to the object.\n\n signature (Optional[str]):\n Callable signature if the object represents a callable.\n\n docstring (Optional[str]):\n Raw docstring text extracted from the source code.\n\n members (Dict[str, DocObject]):\n Mapping of member names to child `DocObject` instances.", "docstring": "Represents a documented Python object (class, function, method, etc.).\n\nAttributes:\n name: Local name of the object.\n kind: Type of object (e.g., 'class', 'function', 'attribute').\n path: Full dotted import path to the object.\n signature: Callable signature, if applicable.\n docstring: Raw docstring content extracted from the source.\n members: Dictionary mapping member names to their DocObject representations.",
"members": { "members": {
"name": { "name": {
"name": "name", "name": "name",
@@ -78,22 +78,22 @@
"name": "add_member", "name": "add_member",
"kind": "function", "kind": "function",
"path": "docforge.models.object.DocObject.add_member", "path": "docforge.models.object.DocObject.add_member",
"signature": "<bound method Function.signature of Function('add_member', 77, 87)>", "signature": "<bound method Function.signature of Function('add_member', 48, 55)>",
"docstring": "Add a child documentation object.\n\nThis is typically used when attaching methods to classes or\nnested objects to their parent containers.\n\nArgs:\n obj: Documentation object to add as a member." "docstring": "Add a child member to this object (e.g., a method to a class).\n\nArgs:\n obj: The child DocObject to add."
}, },
"get_member": { "get_member": {
"name": "get_member", "name": "get_member",
"kind": "function", "kind": "function",
"path": "docforge.models.object.DocObject.get_member", "path": "docforge.models.object.DocObject.get_member",
"signature": "<bound method Function.signature of Function('get_member', 89, 105)>", "signature": "<bound method Function.signature of Function('get_member', 57, 67)>",
"docstring": "Retrieve a member object by name.\n\nArgs:\n name (str):\n Name of the member to retrieve.\n\nReturns:\n DocObject:\n The corresponding `DocObject` instance.\n\nRaises:\n KeyError:\n If the member does not exist." "docstring": "Retrieve a child member by name.\n\nArgs:\n name: The name of the member.\n\nReturns:\n The requested DocObject."
}, },
"get_all_members": { "get_all_members": {
"name": "get_all_members", "name": "get_all_members",
"kind": "function", "kind": "function",
"path": "docforge.models.object.DocObject.get_all_members", "path": "docforge.models.object.DocObject.get_all_members",
"signature": "<bound method Function.signature of Function('get_all_members', 107, 115)>", "signature": "<bound method Function.signature of Function('get_all_members', 69, 76)>",
"docstring": "Return all child members of the object.\n\nReturns:\n Iterable[DocObject]:\n An iterable of `DocObject` instances representing nested members." "docstring": "Get all members of this object.\n\nReturns:\n An iterable of child DocObject instances."
} }
} }
} }

30
mcp_docs/modules/docforge.models.project.json
View File

@@ -2,7 +2,7 @@
"module": "docforge.models.project", "module": "docforge.models.project",
"content": { "content": {
"path": "docforge.models.project", "path": "docforge.models.project",
"docstring": "# Summary\n\nDocumentation model representing a project.\n\nThis module defines the `Project` class, the top-level container used by\ndoc-forge to represent a documented codebase. A `Project` aggregates multiple\nmodules and provides access to them through a unified interface.", "docstring": "This module defines the Project class, the top-level container for a documented\nproject. It aggregates multiple Module instances into a single named entity.",
"objects": { "objects": {
"Dict": { "Dict": {
"name": "Dict", "name": "Dict",
@@ -23,7 +23,7 @@
"kind": "class", "kind": "class",
"path": "docforge.models.project.Module", "path": "docforge.models.project.Module",
"signature": "<bound method Alias.signature of Alias('Module', 'docforge.models.module.Module')>", "signature": "<bound method Alias.signature of Alias('Module', 'docforge.models.module.Module')>",
"docstring": "Representation of a documented Python module or package.\n\nA `Module` stores metadata about the module itself and maintains a\ncollection of top-level documentation objects discovered during\nintrospection.\n\nAttributes:\n path (str):\n Dotted import path of the module.\n\n docstring (Optional[str]):\n Module-level documentation string, if present.\n\n members (Dict[str, DocObject]):\n Mapping of object names to their corresponding `DocObject` representations.", "docstring": "Represents a documented Python module or package.\n\nAttributes:\n path: Dotted import path of the module.\n docstring: Module-level docstring content.\n members: Dictionary mapping object names to their DocObject representations.",
"members": { "members": {
"path": { "path": {
"name": "path", "name": "path",
@@ -51,21 +51,21 @@
"kind": "function", "kind": "function",
"path": "docforge.models.project.Module.add_object", "path": "docforge.models.project.Module.add_object",
"signature": "<bound method Alias.signature of Alias('add_object', 'docforge.models.module.Module.add_object')>", "signature": "<bound method Alias.signature of Alias('add_object', 'docforge.models.module.Module.add_object')>",
"docstring": "Add a documented object to the module.\n\nArgs:\n obj (DocObject):\n Documentation object to register as a top-level member of the module." "docstring": "Add a documented object to the module.\n\nArgs:\n obj: The object to add."
}, },
"get_object": { "get_object": {
"name": "get_object", "name": "get_object",
"kind": "function", "kind": "function",
"path": "docforge.models.project.Module.get_object", "path": "docforge.models.project.Module.get_object",
"signature": "<bound method Alias.signature of Alias('get_object', 'docforge.models.module.Module.get_object')>", "signature": "<bound method Alias.signature of Alias('get_object', 'docforge.models.module.Module.get_object')>",
"docstring": "Retrieve a documented object by name.\n\nArgs:\n name (str):\n Name of the object to retrieve.\n\nReturns:\n DocObject:\n The corresponding `DocObject` instance.\n\nRaises:\n KeyError:\n If no object with the given name exists." "docstring": "Retrieve a member object by name.\n\nArgs:\n name: The name of the object.\n\nReturns:\n The requested DocObject."
}, },
"get_all_objects": { "get_all_objects": {
"name": "get_all_objects", "name": "get_all_objects",
"kind": "function", "kind": "function",
"path": "docforge.models.project.Module.get_all_objects", "path": "docforge.models.project.Module.get_all_objects",
"signature": "<bound method Alias.signature of Alias('get_all_objects', 'docforge.models.module.Module.get_all_objects')>", "signature": "<bound method Alias.signature of Alias('get_all_objects', 'docforge.models.module.Module.get_all_objects')>",
"docstring": "Return all top-level documentation objects in the module.\n\nReturns:\n Iterable[DocObject]:\n An iterable of `DocObject` instances representing the module's public members." "docstring": "Get all top-level objects in the module.\n\nReturns:\n An iterable of DocObject instances."
} }
} }
}, },
@@ -73,8 +73,8 @@
"name": "Project", "name": "Project",
"kind": "class", "kind": "class",
"path": "docforge.models.project.Project", "path": "docforge.models.project.Project",
"signature": "<bound method Class.signature of Class('Project', 16, 88)>", "signature": "<bound method Class.signature of Class('Project', 11, 67)>",
"docstring": "Representation of a documentation project.\n\nA `Project` serves as the root container for all modules discovered during\nintrospection. Each module is stored by its dotted import path.\n\nAttributes:\n name (str):\n Name of the project.\n\n modules (Dict[str, Module]):\n Mapping of module paths to `Module` instances.", "docstring": "Represents a documentation project, serving as a container for modules.\n\nAttributes:\n name: Name of the project.\n modules: Dictionary mapping module paths to Module instances.",
"members": { "members": {
"name": { "name": {
"name": "name", "name": "name",
@@ -94,29 +94,29 @@
"name": "add_module", "name": "add_module",
"kind": "function", "kind": "function",
"path": "docforge.models.project.Project.add_module", "path": "docforge.models.project.Project.add_module",
"signature": "<bound method Function.signature of Function('add_module', 42, 50)>", "signature": "<bound method Function.signature of Function('add_module', 30, 37)>",
"docstring": "Register a module in the project.\n\nArgs:\n module (Module):\n Module instance to add to the project." "docstring": "Add a module to the project.\n\nArgs:\n module: The module to add."
}, },
"get_module": { "get_module": {
"name": "get_module", "name": "get_module",
"kind": "function", "kind": "function",
"path": "docforge.models.project.Project.get_module", "path": "docforge.models.project.Project.get_module",
"signature": "<bound method Function.signature of Function('get_module', 52, 68)>", "signature": "<bound method Function.signature of Function('get_module', 39, 49)>",
"docstring": "Retrieve a module by its dotted path.\n\nArgs:\n path (str):\n Fully qualified dotted module path (for example `pkg.module`).\n\nReturns:\n Module:\n The corresponding `Module` instance.\n\nRaises:\n KeyError:\n If the module does not exist in the project." "docstring": "Retrieve a module by its dotted path.\n\nArgs:\n path: The dotted path of the module (e.g., 'pkg.mod').\n\nReturns:\n The requested Module."
}, },
"get_all_modules": { "get_all_modules": {
"name": "get_all_modules", "name": "get_all_modules",
"kind": "function", "kind": "function",
"path": "docforge.models.project.Project.get_all_modules", "path": "docforge.models.project.Project.get_all_modules",
"signature": "<bound method Function.signature of Function('get_all_modules', 70, 78)>", "signature": "<bound method Function.signature of Function('get_all_modules', 51, 58)>",
"docstring": "Return all modules contained in the project.\n\nReturns:\n Iterable[Module]:\n An iterable of `Module` instances." "docstring": "Get all modules in the project.\n\nReturns:\n An iterable of Module objects."
}, },
"get_module_list": { "get_module_list": {
"name": "get_module_list", "name": "get_module_list",
"kind": "function", "kind": "function",
"path": "docforge.models.project.Project.get_module_list", "path": "docforge.models.project.Project.get_module_list",
"signature": "<bound method Function.signature of Function('get_module_list', 80, 88)>", "signature": "<bound method Function.signature of Function('get_module_list', 60, 67)>",
"docstring": "Return the list of module import paths.\n\nReturns:\n list[str]:\n A list containing the dotted paths of all modules in the project." "docstring": "Get the list of all module dotted paths.\n\nReturns:\n A list of module paths."
} }
} }
} }

72
mcp_docs/modules/docforge.nav.json
View File

@@ -2,14 +2,14 @@
"module": "docforge.nav", "module": "docforge.nav",
"content": { "content": {
"path": "docforge.nav", "path": "docforge.nav",
"docstring": "Navigation layer for doc-forge.\n\nThe ``docforge.nav`` package manages the relationship between the logical\ndocumentation structure defined by the user and the physical documentation\nfiles generated on disk.\n\n---\n\nWorkflow\n--------\n\n1. **Specification** – Users define navigation intent in ``docforge.nav.yml``.\n2. **Resolution** – ``resolve_nav`` expands patterns and matches them against\n generated Markdown files.\n3. **Emission** – ``MkDocsNavEmitter`` converts the resolved structure into\n the YAML navigation format required by ``mkdocs.yml``.\n\nThis layer separates documentation organization from the underlying source\ncode layout, enabling flexible grouping, ordering, and navigation structures\nindependent of module hierarchy.\n\n---", "docstring": "# Navigation Layer\n\nThe `docforge.nav` package manages the mapping between the logical documentation\nstructure and the physical files on disk.\n\n## Workflow\n\n1. **Spec Definition**: Users define navigation intent in `docforge.nav.yml`.\n2. **Resolution**: `resolve_nav` matches patterns in the spec to generated `.md` files.\n3. **Emission**: `MkDocsNavEmitter` produces the final YAML structure for `mkdocs.yml`.\n\nThis abstraction allows doc-forge to support complex grouping and ordering\nindependently of the source code's physical layout.",
"objects": { "objects": {
"NavSpec": { "NavSpec": {
"name": "NavSpec", "name": "NavSpec",
"kind": "class", "kind": "class",
"path": "docforge.nav.NavSpec", "path": "docforge.nav.NavSpec",
"signature": "<bound method Alias.signature of Alias('NavSpec', 'docforge.nav.spec.NavSpec')>", "signature": "<bound method Alias.signature of Alias('NavSpec', 'docforge.nav.spec.NavSpec')>",
"docstring": "Parsed representation of a navigation specification.\n\nA ``NavSpec`` describes the intended documentation navigation layout before\nit is resolved against the filesystem.\n\nAttributes:\n home: Relative path to the documentation home page (for example\n ``index.md``).\n groups: Mapping of navigation group titles to lists of file patterns\n or glob expressions.", "docstring": "Parsed representation of the docforge navigation specification file.\n\nAttributes:\n home: Path to the home document (e.g., 'index.md').\n groups: Mapping of group titles to lists of path patterns/globs.",
"members": { "members": {
"home": { "home": {
"name": "home", "name": "home",
@@ -30,14 +30,14 @@
"kind": "function", "kind": "function",
"path": "docforge.nav.NavSpec.load", "path": "docforge.nav.NavSpec.load",
"signature": "<bound method Alias.signature of Alias('load', 'docforge.nav.spec.NavSpec.load')>", "signature": "<bound method Alias.signature of Alias('load', 'docforge.nav.spec.NavSpec.load')>",
"docstring": "Load a navigation specification from a YAML file.\n\nArgs:\n path: Filesystem path to the navigation specification file.\n\nReturns:\n A ``NavSpec`` instance representing the parsed configuration.\n\nRaises:\n FileNotFoundError: If the specified file does not exist.\n ValueError: If the file contents are not a valid navigation\n specification." "docstring": "Load a NavSpec from a YAML file.\n\nArgs:\n path: The filesystem path to the YAML file.\n\nReturns:\n A NavSpec instance.\n\nRaises:\n FileNotFoundError: If the path does not exist.\n ValueError: If the file content is not a valid NavSpec mapping."
}, },
"all_patterns": { "all_patterns": {
"name": "all_patterns", "name": "all_patterns",
"kind": "function", "kind": "function",
"path": "docforge.nav.NavSpec.all_patterns", "path": "docforge.nav.NavSpec.all_patterns",
"signature": "<bound method Alias.signature of Alias('all_patterns', 'docforge.nav.spec.NavSpec.all_patterns')>", "signature": "<bound method Alias.signature of Alias('all_patterns', 'docforge.nav.spec.NavSpec.all_patterns')>",
"docstring": "Return all path patterns referenced by the specification.\n\nReturns:\n A list containing the home document (if defined) and all\n group pattern entries." "docstring": "Get all path patterns referenced in the specification.\n\nReturns:\n A list of all patterns (home plus all groups)."
} }
} }
}, },
@@ -46,14 +46,14 @@
"kind": "function", "kind": "function",
"path": "docforge.nav.load_nav_spec", "path": "docforge.nav.load_nav_spec",
"signature": "<bound method Alias.signature of Alias('load_nav_spec', 'docforge.nav.spec.load_nav_spec')>", "signature": "<bound method Alias.signature of Alias('load_nav_spec', 'docforge.nav.spec.load_nav_spec')>",
"docstring": "Load a navigation specification file.\n\nThis helper function reads a YAML navigation file and constructs a\ncorresponding ``NavSpec`` instance.\n\nArgs:\n path: Path to the navigation specification file.\n\nReturns:\n A ``NavSpec`` instance representing the parsed specification.\n\nRaises:\n FileNotFoundError: If the specification file does not exist.\n ValueError: If the YAML structure is invalid." "docstring": "Utility function to load a NavSpec from a file.\n\nArgs:\n path: Path to the navigation specification file.\n\nReturns:\n A loaded NavSpec instance."
}, },
"ResolvedNav": { "ResolvedNav": {
"name": "ResolvedNav", "name": "ResolvedNav",
"kind": "class", "kind": "class",
"path": "docforge.nav.ResolvedNav", "path": "docforge.nav.ResolvedNav",
"signature": "<bound method Alias.signature of Alias('ResolvedNav', 'docforge.nav.resolver.ResolvedNav')>", "signature": "<bound method Alias.signature of Alias('ResolvedNav', 'docforge.nav.resolver.ResolvedNav')>",
"docstring": "Resolved navigation structure.\n\nA ``ResolvedNav`` represents navigation data after glob patterns have been\nexpanded and paths validated against the filesystem.\n\nAttributes:\n home: Relative path to the documentation home page.\n groups: Mapping of navigation group titles to lists of resolved\n documentation file paths.", "docstring": "Represents a navigation structure where all patterns and paths have been\nresolved against the actual filesystem contents.\n\nAttributes:\n home: Resolved relative path to the home page.\n groups: Mapping of group titles to lists of absolute or relative Path objects.",
"members": { "members": {
"home": { "home": {
"name": "home", "name": "home",
@@ -74,7 +74,7 @@
"kind": "function", "kind": "function",
"path": "docforge.nav.ResolvedNav.all_files", "path": "docforge.nav.ResolvedNav.all_files",
"signature": "<bound method Alias.signature of Alias('all_files', 'docforge.nav.resolver.ResolvedNav.all_files')>", "signature": "<bound method Alias.signature of Alias('all_files', 'docforge.nav.resolver.ResolvedNav.all_files')>",
"docstring": "Iterate over all files referenced by the navigation structure.\n\nReturns:\n An iterable of ``Path`` objects representing documentation files.\n\nRaises:\n RuntimeError: If the home page is defined but the documentation\n root is not available for resolution." "docstring": "Get an iterable of all resolved files in the navigation structure.\n\nReturns:\n An iterable of Path objects."
} }
} }
}, },
@@ -83,21 +83,21 @@
"kind": "function", "kind": "function",
"path": "docforge.nav.resolve_nav", "path": "docforge.nav.resolve_nav",
"signature": "<bound method Alias.signature of Alias('resolve_nav', 'docforge.nav.resolver.resolve_nav')>", "signature": "<bound method Alias.signature of Alias('resolve_nav', 'docforge.nav.resolver.resolve_nav')>",
"docstring": "Resolve a navigation specification against the filesystem.\n\nThe function expands glob patterns defined in a ``NavSpec`` and verifies\nthat referenced documentation files exist within the documentation root.\n\nArgs:\n spec: Navigation specification describing documentation layout.\n docs_root: Root directory containing documentation Markdown files.\n\nReturns:\n A ``ResolvedNav`` instance containing validated navigation paths.\n\nRaises:\n FileNotFoundError: If the documentation root does not exist or a\n navigation pattern does not match any files." "docstring": "Create a ResolvedNav by processing a NavSpec against the filesystem.\nThis expands globs and validates the existence of referenced files.\n\nArgs:\n spec: The navigation specification to resolve.\n docs_root: The root directory for documentation files.\n\nReturns:\n A ResolvedNav instance.\n\nRaises:\n FileNotFoundError: If a pattern doesn't match any files or the docs_root doesn't exist."
}, },
"MkDocsNavEmitter": { "MkDocsNavEmitter": {
"name": "MkDocsNavEmitter", "name": "MkDocsNavEmitter",
"kind": "class", "kind": "class",
"path": "docforge.nav.MkDocsNavEmitter", "path": "docforge.nav.MkDocsNavEmitter",
"signature": "<bound method Alias.signature of Alias('MkDocsNavEmitter', 'docforge.nav.mkdocs.MkDocsNavEmitter')>", "signature": "<bound method Alias.signature of Alias('MkDocsNavEmitter', 'docforge.nav.mkdocs.MkDocsNavEmitter')>",
"docstring": "Emit MkDocs navigation structures from resolved navigation data.\n\nThe emitter transforms a ``ResolvedNav`` object into the YAML-compatible\nlist structure expected by the MkDocs ``nav`` configuration field.", "docstring": "Emitter responsible for transforming a ResolvedNav into an MkDocs-compatible\nnavigation structure.",
"members": { "members": {
"emit": { "emit": {
"name": "emit", "name": "emit",
"kind": "function", "kind": "function",
"path": "docforge.nav.MkDocsNavEmitter.emit", "path": "docforge.nav.MkDocsNavEmitter.emit",
"signature": "<bound method Alias.signature of Alias('emit', 'docforge.nav.mkdocs.MkDocsNavEmitter.emit')>", "signature": "<bound method Alias.signature of Alias('emit', 'docforge.nav.mkdocs.MkDocsNavEmitter.emit')>",
"docstring": "Generate a navigation structure for ``mkdocs.yml``.\n\nArgs:\n nav: Resolved navigation data describing documentation groups\n and their associated Markdown files.\n\nReturns:\n A list of dictionaries representing the MkDocs navigation layout.\n Each dictionary maps a navigation label to a page or a list of\n pages." "docstring": "Generate a list of navigation entries for mkdocs.yml.\n\nArgs:\n nav: The resolved navigation data.\n\nReturns:\n A list of dictionary mappings representing the MkDocs navigation."
} }
} }
}, },
@@ -106,7 +106,7 @@
"kind": "module", "kind": "module",
"path": "docforge.nav.mkdocs", "path": "docforge.nav.mkdocs",
"signature": null, "signature": null,
"docstring": "MkDocs navigation emitter.\n\nThis module provides the ``MkDocsNavEmitter`` class, which converts a\n``ResolvedNav`` instance into the navigation structure required by the\nMkDocs ``nav`` configuration.", "docstring": "This module provides the MkDocsNavEmitter, which converts a ResolvedNav instance\ninto the specific YAML-ready list structure expected by the MkDocs 'nav'\nconfiguration.",
"members": { "members": {
"Path": { "Path": {
"name": "Path", "name": "Path",
@@ -141,7 +141,7 @@
"kind": "class", "kind": "class",
"path": "docforge.nav.mkdocs.ResolvedNav", "path": "docforge.nav.mkdocs.ResolvedNav",
"signature": "<bound method Alias.signature of Alias('ResolvedNav', 'docforge.nav.resolver.ResolvedNav')>", "signature": "<bound method Alias.signature of Alias('ResolvedNav', 'docforge.nav.resolver.ResolvedNav')>",
"docstring": "Resolved navigation structure.\n\nA ``ResolvedNav`` represents navigation data after glob patterns have been\nexpanded and paths validated against the filesystem.\n\nAttributes:\n home: Relative path to the documentation home page.\n groups: Mapping of navigation group titles to lists of resolved\n documentation file paths.", "docstring": "Represents a navigation structure where all patterns and paths have been\nresolved against the actual filesystem contents.\n\nAttributes:\n home: Resolved relative path to the home page.\n groups: Mapping of group titles to lists of absolute or relative Path objects.",
"members": { "members": {
"home": { "home": {
"name": "home", "name": "home",
@@ -162,7 +162,7 @@
"kind": "function", "kind": "function",
"path": "docforge.nav.mkdocs.ResolvedNav.all_files", "path": "docforge.nav.mkdocs.ResolvedNav.all_files",
"signature": "<bound method Alias.signature of Alias('all_files', 'docforge.nav.resolver.ResolvedNav.all_files')>", "signature": "<bound method Alias.signature of Alias('all_files', 'docforge.nav.resolver.ResolvedNav.all_files')>",
"docstring": "Iterate over all files referenced by the navigation structure.\n\nReturns:\n An iterable of ``Path`` objects representing documentation files.\n\nRaises:\n RuntimeError: If the home page is defined but the documentation\n root is not available for resolution." "docstring": "Get an iterable of all resolved files in the navigation structure.\n\nReturns:\n An iterable of Path objects."
} }
} }
}, },
@@ -170,15 +170,15 @@
"name": "MkDocsNavEmitter", "name": "MkDocsNavEmitter",
"kind": "class", "kind": "class",
"path": "docforge.nav.mkdocs.MkDocsNavEmitter", "path": "docforge.nav.mkdocs.MkDocsNavEmitter",
"signature": "<bound method Class.signature of Class('MkDocsNavEmitter', 15, 81)>", "signature": "<bound method Class.signature of Class('MkDocsNavEmitter', 13, 72)>",
"docstring": "Emit MkDocs navigation structures from resolved navigation data.\n\nThe emitter transforms a ``ResolvedNav`` object into the YAML-compatible\nlist structure expected by the MkDocs ``nav`` configuration field.", "docstring": "Emitter responsible for transforming a ResolvedNav into an MkDocs-compatible\nnavigation structure.",
"members": { "members": {
"emit": { "emit": {
"name": "emit", "name": "emit",
"kind": "function", "kind": "function",
"path": "docforge.nav.mkdocs.MkDocsNavEmitter.emit", "path": "docforge.nav.mkdocs.MkDocsNavEmitter.emit",
"signature": "<bound method Function.signature of Function('emit', 23, 51)>", "signature": "<bound method Function.signature of Function('emit', 19, 44)>",
"docstring": "Generate a navigation structure for ``mkdocs.yml``.\n\nArgs:\n nav: Resolved navigation data describing documentation groups\n and their associated Markdown files.\n\nReturns:\n A list of dictionaries representing the MkDocs navigation layout.\n Each dictionary maps a navigation label to a page or a list of\n pages." "docstring": "Generate a list of navigation entries for mkdocs.yml.\n\nArgs:\n nav: The resolved navigation data.\n\nReturns:\n A list of dictionary mappings representing the MkDocs navigation."
} }
} }
} }
@@ -189,7 +189,7 @@
"kind": "module", "kind": "module",
"path": "docforge.nav.resolver", "path": "docforge.nav.resolver",
"signature": null, "signature": null,
"docstring": "Navigation resolution utilities.\n\nThis module resolves a ``NavSpec`` against the filesystem by expanding glob\npatterns and validating that referenced documentation files exist.", "docstring": "This module contains the logic for resolving a NavSpec against the physical\nfilesystem. It expands globs and validates that all referenced documents\nactually exist on disk.",
"members": { "members": {
"Path": { "Path": {
"name": "Path", "name": "Path",
@@ -231,7 +231,7 @@
"kind": "class", "kind": "class",
"path": "docforge.nav.resolver.NavSpec", "path": "docforge.nav.resolver.NavSpec",
"signature": "<bound method Alias.signature of Alias('NavSpec', 'docforge.nav.spec.NavSpec')>", "signature": "<bound method Alias.signature of Alias('NavSpec', 'docforge.nav.spec.NavSpec')>",
"docstring": "Parsed representation of a navigation specification.\n\nA ``NavSpec`` describes the intended documentation navigation layout before\nit is resolved against the filesystem.\n\nAttributes:\n home: Relative path to the documentation home page (for example\n ``index.md``).\n groups: Mapping of navigation group titles to lists of file patterns\n or glob expressions.", "docstring": "Parsed representation of the docforge navigation specification file.\n\nAttributes:\n home: Path to the home document (e.g., 'index.md').\n groups: Mapping of group titles to lists of path patterns/globs.",
"members": { "members": {
"home": { "home": {
"name": "home", "name": "home",
@@ -252,14 +252,14 @@
"kind": "function", "kind": "function",
"path": "docforge.nav.resolver.NavSpec.load", "path": "docforge.nav.resolver.NavSpec.load",
"signature": "<bound method Alias.signature of Alias('load', 'docforge.nav.spec.NavSpec.load')>", "signature": "<bound method Alias.signature of Alias('load', 'docforge.nav.spec.NavSpec.load')>",
"docstring": "Load a navigation specification from a YAML file.\n\nArgs:\n path: Filesystem path to the navigation specification file.\n\nReturns:\n A ``NavSpec`` instance representing the parsed configuration.\n\nRaises:\n FileNotFoundError: If the specified file does not exist.\n ValueError: If the file contents are not a valid navigation\n specification." "docstring": "Load a NavSpec from a YAML file.\n\nArgs:\n path: The filesystem path to the YAML file.\n\nReturns:\n A NavSpec instance.\n\nRaises:\n FileNotFoundError: If the path does not exist.\n ValueError: If the file content is not a valid NavSpec mapping."
}, },
"all_patterns": { "all_patterns": {
"name": "all_patterns", "name": "all_patterns",
"kind": "function", "kind": "function",
"path": "docforge.nav.resolver.NavSpec.all_patterns", "path": "docforge.nav.resolver.NavSpec.all_patterns",
"signature": "<bound method Alias.signature of Alias('all_patterns', 'docforge.nav.spec.NavSpec.all_patterns')>", "signature": "<bound method Alias.signature of Alias('all_patterns', 'docforge.nav.spec.NavSpec.all_patterns')>",
"docstring": "Return all path patterns referenced by the specification.\n\nReturns:\n A list containing the home document (if defined) and all\n group pattern entries." "docstring": "Get all path patterns referenced in the specification.\n\nReturns:\n A list of all patterns (home plus all groups)."
} }
} }
}, },
@@ -267,8 +267,8 @@
"name": "ResolvedNav", "name": "ResolvedNav",
"kind": "class", "kind": "class",
"path": "docforge.nav.resolver.ResolvedNav", "path": "docforge.nav.resolver.ResolvedNav",
"signature": "<bound method Class.signature of Class('ResolvedNav', 16, 65)>", "signature": "<bound method Class.signature of Class('ResolvedNav', 15, 56)>",
"docstring": "Resolved navigation structure.\n\nA ``ResolvedNav`` represents navigation data after glob patterns have been\nexpanded and paths validated against the filesystem.\n\nAttributes:\n home: Relative path to the documentation home page.\n groups: Mapping of navigation group titles to lists of resolved\n documentation file paths.", "docstring": "Represents a navigation structure where all patterns and paths have been\nresolved against the actual filesystem contents.\n\nAttributes:\n home: Resolved relative path to the home page.\n groups: Mapping of group titles to lists of absolute or relative Path objects.",
"members": { "members": {
"home": { "home": {
"name": "home", "name": "home",
@@ -288,8 +288,8 @@
"name": "all_files", "name": "all_files",
"kind": "function", "kind": "function",
"path": "docforge.nav.resolver.ResolvedNav.all_files", "path": "docforge.nav.resolver.ResolvedNav.all_files",
"signature": "<bound method Function.signature of Function('all_files', 47, 65)>", "signature": "<bound method Function.signature of Function('all_files', 43, 56)>",
"docstring": "Iterate over all files referenced by the navigation structure.\n\nReturns:\n An iterable of ``Path`` objects representing documentation files.\n\nRaises:\n RuntimeError: If the home page is defined but the documentation\n root is not available for resolution." "docstring": "Get an iterable of all resolved files in the navigation structure.\n\nReturns:\n An iterable of Path objects."
} }
} }
}, },
@@ -297,8 +297,8 @@
"name": "resolve_nav", "name": "resolve_nav",
"kind": "function", "kind": "function",
"path": "docforge.nav.resolver.resolve_nav", "path": "docforge.nav.resolver.resolve_nav",
"signature": "<bound method Function.signature of Function('resolve_nav', 68, 136)>", "signature": "<bound method Function.signature of Function('resolve_nav', 59, 124)>",
"docstring": "Resolve a navigation specification against the filesystem.\n\nThe function expands glob patterns defined in a ``NavSpec`` and verifies\nthat referenced documentation files exist within the documentation root.\n\nArgs:\n spec: Navigation specification describing documentation layout.\n docs_root: Root directory containing documentation Markdown files.\n\nReturns:\n A ``ResolvedNav`` instance containing validated navigation paths.\n\nRaises:\n FileNotFoundError: If the documentation root does not exist or a\n navigation pattern does not match any files." "docstring": "Create a ResolvedNav by processing a NavSpec against the filesystem.\nThis expands globs and validates the existence of referenced files.\n\nArgs:\n spec: The navigation specification to resolve.\n docs_root: The root directory for documentation files.\n\nReturns:\n A ResolvedNav instance.\n\nRaises:\n FileNotFoundError: If a pattern doesn't match any files or the docs_root doesn't exist."
}, },
"Optional": { "Optional": {
"name": "Optional", "name": "Optional",
@@ -314,7 +314,7 @@
"kind": "module", "kind": "module",
"path": "docforge.nav.spec", "path": "docforge.nav.spec",
"signature": null, "signature": null,
"docstring": "Navigation specification model.\n\nThis module defines the ``NavSpec`` class, which represents the navigation\nstructure defined by the user in the doc-forge navigation specification\n(typically ``docforge.nav.yml``).", "docstring": "This module defines the NavSpec class, which represents the user's intent for\ndocumentation navigation as defined in a YAML specification (usually\ndocforge.nav.yml).",
"members": { "members": {
"Path": { "Path": {
"name": "Path", "name": "Path",
@@ -355,8 +355,8 @@
"name": "NavSpec", "name": "NavSpec",
"kind": "class", "kind": "class",
"path": "docforge.nav.spec.NavSpec", "path": "docforge.nav.spec.NavSpec",
"signature": "<bound method Class.signature of Class('NavSpec', 15, 104)>", "signature": "<bound method Class.signature of Class('NavSpec', 13, 91)>",
"docstring": "Parsed representation of a navigation specification.\n\nA ``NavSpec`` describes the intended documentation navigation layout before\nit is resolved against the filesystem.\n\nAttributes:\n home: Relative path to the documentation home page (for example\n ``index.md``).\n groups: Mapping of navigation group titles to lists of file patterns\n or glob expressions.", "docstring": "Parsed representation of the docforge navigation specification file.\n\nAttributes:\n home: Path to the home document (e.g., 'index.md').\n groups: Mapping of group titles to lists of path patterns/globs.",
"members": { "members": {
"home": { "home": {
"name": "home", "name": "home",
@@ -376,15 +376,15 @@
"name": "load", "name": "load",
"kind": "function", "kind": "function",
"path": "docforge.nav.spec.NavSpec.load", "path": "docforge.nav.spec.NavSpec.load",
"signature": "<bound method Function.signature of Function('load', 45, 86)>", "signature": "<bound method Function.signature of Function('load', 37, 77)>",
"docstring": "Load a navigation specification from a YAML file.\n\nArgs:\n path: Filesystem path to the navigation specification file.\n\nReturns:\n A ``NavSpec`` instance representing the parsed configuration.\n\nRaises:\n FileNotFoundError: If the specified file does not exist.\n ValueError: If the file contents are not a valid navigation\n specification." "docstring": "Load a NavSpec from a YAML file.\n\nArgs:\n path: The filesystem path to the YAML file.\n\nReturns:\n A NavSpec instance.\n\nRaises:\n FileNotFoundError: If the path does not exist.\n ValueError: If the file content is not a valid NavSpec mapping."
}, },
"all_patterns": { "all_patterns": {
"name": "all_patterns", "name": "all_patterns",
"kind": "function", "kind": "function",
"path": "docforge.nav.spec.NavSpec.all_patterns", "path": "docforge.nav.spec.NavSpec.all_patterns",
"signature": "<bound method Function.signature of Function('all_patterns', 88, 104)>", "signature": "<bound method Function.signature of Function('all_patterns', 79, 91)>",
"docstring": "Return all path patterns referenced by the specification.\n\nReturns:\n A list containing the home document (if defined) and all\n group pattern entries." "docstring": "Get all path patterns referenced in the specification.\n\nReturns:\n A list of all patterns (home plus all groups)."
} }
} }
}, },
@@ -392,8 +392,8 @@
"name": "load_nav_spec", "name": "load_nav_spec",
"kind": "function", "kind": "function",
"path": "docforge.nav.spec.load_nav_spec", "path": "docforge.nav.spec.load_nav_spec",
"signature": "<bound method Function.signature of Function('load_nav_spec', 107, 135)>", "signature": "<bound method Function.signature of Function('load_nav_spec', 94, 114)>",
"docstring": "Load a navigation specification file.\n\nThis helper function reads a YAML navigation file and constructs a\ncorresponding ``NavSpec`` instance.\n\nArgs:\n path: Path to the navigation specification file.\n\nReturns:\n A ``NavSpec`` instance representing the parsed specification.\n\nRaises:\n FileNotFoundError: If the specification file does not exist.\n ValueError: If the YAML structure is invalid." "docstring": "Utility function to load a NavSpec from a file.\n\nArgs:\n path: Path to the navigation specification file.\n\nReturns:\n A loaded NavSpec instance."
} }
} }
} }

14
mcp_docs/modules/docforge.nav.mkdocs.json
View File

@@ -2,7 +2,7 @@
"module": "docforge.nav.mkdocs", "module": "docforge.nav.mkdocs",
"content": { "content": {
"path": "docforge.nav.mkdocs", "path": "docforge.nav.mkdocs",
"docstring": "MkDocs navigation emitter.\n\nThis module provides the ``MkDocsNavEmitter`` class, which converts a\n``ResolvedNav`` instance into the navigation structure required by the\nMkDocs ``nav`` configuration.", "docstring": "This module provides the MkDocsNavEmitter, which converts a ResolvedNav instance\ninto the specific YAML-ready list structure expected by the MkDocs 'nav'\nconfiguration.",
"objects": { "objects": {
"Path": { "Path": {
"name": "Path", "name": "Path",
@@ -37,7 +37,7 @@
"kind": "class", "kind": "class",
"path": "docforge.nav.mkdocs.ResolvedNav", "path": "docforge.nav.mkdocs.ResolvedNav",
"signature": "<bound method Alias.signature of Alias('ResolvedNav', 'docforge.nav.resolver.ResolvedNav')>", "signature": "<bound method Alias.signature of Alias('ResolvedNav', 'docforge.nav.resolver.ResolvedNav')>",
"docstring": "Resolved navigation structure.\n\nA ``ResolvedNav`` represents navigation data after glob patterns have been\nexpanded and paths validated against the filesystem.\n\nAttributes:\n home: Relative path to the documentation home page.\n groups: Mapping of navigation group titles to lists of resolved\n documentation file paths.", "docstring": "Represents a navigation structure where all patterns and paths have been\nresolved against the actual filesystem contents.\n\nAttributes:\n home: Resolved relative path to the home page.\n groups: Mapping of group titles to lists of absolute or relative Path objects.",
"members": { "members": {
"home": { "home": {
"name": "home", "name": "home",
@@ -58,7 +58,7 @@
"kind": "function", "kind": "function",
"path": "docforge.nav.mkdocs.ResolvedNav.all_files", "path": "docforge.nav.mkdocs.ResolvedNav.all_files",
"signature": "<bound method Alias.signature of Alias('all_files', 'docforge.nav.resolver.ResolvedNav.all_files')>", "signature": "<bound method Alias.signature of Alias('all_files', 'docforge.nav.resolver.ResolvedNav.all_files')>",
"docstring": "Iterate over all files referenced by the navigation structure.\n\nReturns:\n An iterable of ``Path`` objects representing documentation files.\n\nRaises:\n RuntimeError: If the home page is defined but the documentation\n root is not available for resolution." "docstring": "Get an iterable of all resolved files in the navigation structure.\n\nReturns:\n An iterable of Path objects."
} }
} }
}, },
@@ -66,15 +66,15 @@
"name": "MkDocsNavEmitter", "name": "MkDocsNavEmitter",
"kind": "class", "kind": "class",
"path": "docforge.nav.mkdocs.MkDocsNavEmitter", "path": "docforge.nav.mkdocs.MkDocsNavEmitter",
"signature": "<bound method Class.signature of Class('MkDocsNavEmitter', 15, 81)>", "signature": "<bound method Class.signature of Class('MkDocsNavEmitter', 13, 72)>",
"docstring": "Emit MkDocs navigation structures from resolved navigation data.\n\nThe emitter transforms a ``ResolvedNav`` object into the YAML-compatible\nlist structure expected by the MkDocs ``nav`` configuration field.", "docstring": "Emitter responsible for transforming a ResolvedNav into an MkDocs-compatible\nnavigation structure.",
"members": { "members": {
"emit": { "emit": {
"name": "emit", "name": "emit",
"kind": "function", "kind": "function",
"path": "docforge.nav.mkdocs.MkDocsNavEmitter.emit", "path": "docforge.nav.mkdocs.MkDocsNavEmitter.emit",
"signature": "<bound method Function.signature of Function('emit', 23, 51)>", "signature": "<bound method Function.signature of Function('emit', 19, 44)>",
"docstring": "Generate a navigation structure for ``mkdocs.yml``.\n\nArgs:\n nav: Resolved navigation data describing documentation groups\n and their associated Markdown files.\n\nReturns:\n A list of dictionaries representing the MkDocs navigation layout.\n Each dictionary maps a navigation label to a page or a list of\n pages." "docstring": "Generate a list of navigation entries for mkdocs.yml.\n\nArgs:\n nav: The resolved navigation data.\n\nReturns:\n A list of dictionary mappings representing the MkDocs navigation."
} }
} }
} }

20
mcp_docs/modules/docforge.nav.resolver.json
View File

@@ -2,7 +2,7 @@
"module": "docforge.nav.resolver", "module": "docforge.nav.resolver",
"content": { "content": {
"path": "docforge.nav.resolver", "path": "docforge.nav.resolver",
"docstring": "Navigation resolution utilities.\n\nThis module resolves a ``NavSpec`` against the filesystem by expanding glob\npatterns and validating that referenced documentation files exist.", "docstring": "This module contains the logic for resolving a NavSpec against the physical\nfilesystem. It expands globs and validates that all referenced documents\nactually exist on disk.",
"objects": { "objects": {
"Path": { "Path": {
"name": "Path", "name": "Path",
@@ -44,7 +44,7 @@
"kind": "class", "kind": "class",
"path": "docforge.nav.resolver.NavSpec", "path": "docforge.nav.resolver.NavSpec",
"signature": "<bound method Alias.signature of Alias('NavSpec', 'docforge.nav.spec.NavSpec')>", "signature": "<bound method Alias.signature of Alias('NavSpec', 'docforge.nav.spec.NavSpec')>",
"docstring": "Parsed representation of a navigation specification.\n\nA ``NavSpec`` describes the intended documentation navigation layout before\nit is resolved against the filesystem.\n\nAttributes:\n home: Relative path to the documentation home page (for example\n ``index.md``).\n groups: Mapping of navigation group titles to lists of file patterns\n or glob expressions.", "docstring": "Parsed representation of the docforge navigation specification file.\n\nAttributes:\n home: Path to the home document (e.g., 'index.md').\n groups: Mapping of group titles to lists of path patterns/globs.",
"members": { "members": {
"home": { "home": {
"name": "home", "name": "home",
@@ -65,14 +65,14 @@
"kind": "function", "kind": "function",
"path": "docforge.nav.resolver.NavSpec.load", "path": "docforge.nav.resolver.NavSpec.load",
"signature": "<bound method Alias.signature of Alias('load', 'docforge.nav.spec.NavSpec.load')>", "signature": "<bound method Alias.signature of Alias('load', 'docforge.nav.spec.NavSpec.load')>",
"docstring": "Load a navigation specification from a YAML file.\n\nArgs:\n path: Filesystem path to the navigation specification file.\n\nReturns:\n A ``NavSpec`` instance representing the parsed configuration.\n\nRaises:\n FileNotFoundError: If the specified file does not exist.\n ValueError: If the file contents are not a valid navigation\n specification." "docstring": "Load a NavSpec from a YAML file.\n\nArgs:\n path: The filesystem path to the YAML file.\n\nReturns:\n A NavSpec instance.\n\nRaises:\n FileNotFoundError: If the path does not exist.\n ValueError: If the file content is not a valid NavSpec mapping."
}, },
"all_patterns": { "all_patterns": {
"name": "all_patterns", "name": "all_patterns",
"kind": "function", "kind": "function",
"path": "docforge.nav.resolver.NavSpec.all_patterns", "path": "docforge.nav.resolver.NavSpec.all_patterns",
"signature": "<bound method Alias.signature of Alias('all_patterns', 'docforge.nav.spec.NavSpec.all_patterns')>", "signature": "<bound method Alias.signature of Alias('all_patterns', 'docforge.nav.spec.NavSpec.all_patterns')>",
"docstring": "Return all path patterns referenced by the specification.\n\nReturns:\n A list containing the home document (if defined) and all\n group pattern entries." "docstring": "Get all path patterns referenced in the specification.\n\nReturns:\n A list of all patterns (home plus all groups)."
} }
} }
}, },
@@ -80,8 +80,8 @@
"name": "ResolvedNav", "name": "ResolvedNav",
"kind": "class", "kind": "class",
"path": "docforge.nav.resolver.ResolvedNav", "path": "docforge.nav.resolver.ResolvedNav",
"signature": "<bound method Class.signature of Class('ResolvedNav', 16, 65)>", "signature": "<bound method Class.signature of Class('ResolvedNav', 15, 56)>",
"docstring": "Resolved navigation structure.\n\nA ``ResolvedNav`` represents navigation data after glob patterns have been\nexpanded and paths validated against the filesystem.\n\nAttributes:\n home: Relative path to the documentation home page.\n groups: Mapping of navigation group titles to lists of resolved\n documentation file paths.", "docstring": "Represents a navigation structure where all patterns and paths have been\nresolved against the actual filesystem contents.\n\nAttributes:\n home: Resolved relative path to the home page.\n groups: Mapping of group titles to lists of absolute or relative Path objects.",
"members": { "members": {
"home": { "home": {
"name": "home", "name": "home",
@@ -101,8 +101,8 @@
"name": "all_files", "name": "all_files",
"kind": "function", "kind": "function",
"path": "docforge.nav.resolver.ResolvedNav.all_files", "path": "docforge.nav.resolver.ResolvedNav.all_files",
"signature": "<bound method Function.signature of Function('all_files', 47, 65)>", "signature": "<bound method Function.signature of Function('all_files', 43, 56)>",
"docstring": "Iterate over all files referenced by the navigation structure.\n\nReturns:\n An iterable of ``Path`` objects representing documentation files.\n\nRaises:\n RuntimeError: If the home page is defined but the documentation\n root is not available for resolution." "docstring": "Get an iterable of all resolved files in the navigation structure.\n\nReturns:\n An iterable of Path objects."
} }
} }
}, },
@@ -110,8 +110,8 @@
"name": "resolve_nav", "name": "resolve_nav",
"kind": "function", "kind": "function",
"path": "docforge.nav.resolver.resolve_nav", "path": "docforge.nav.resolver.resolve_nav",
"signature": "<bound method Function.signature of Function('resolve_nav', 68, 136)>", "signature": "<bound method Function.signature of Function('resolve_nav', 59, 124)>",
"docstring": "Resolve a navigation specification against the filesystem.\n\nThe function expands glob patterns defined in a ``NavSpec`` and verifies\nthat referenced documentation files exist within the documentation root.\n\nArgs:\n spec: Navigation specification describing documentation layout.\n docs_root: Root directory containing documentation Markdown files.\n\nReturns:\n A ``ResolvedNav`` instance containing validated navigation paths.\n\nRaises:\n FileNotFoundError: If the documentation root does not exist or a\n navigation pattern does not match any files." "docstring": "Create a ResolvedNav by processing a NavSpec against the filesystem.\nThis expands globs and validates the existence of referenced files.\n\nArgs:\n spec: The navigation specification to resolve.\n docs_root: The root directory for documentation files.\n\nReturns:\n A ResolvedNav instance.\n\nRaises:\n FileNotFoundError: If a pattern doesn't match any files or the docs_root doesn't exist."
}, },
"Optional": { "Optional": {
"name": "Optional", "name": "Optional",

18
mcp_docs/modules/docforge.nav.spec.json
View File

@@ -2,7 +2,7 @@
"module": "docforge.nav.spec", "module": "docforge.nav.spec",
"content": { "content": {
"path": "docforge.nav.spec", "path": "docforge.nav.spec",
"docstring": "Navigation specification model.\n\nThis module defines the ``NavSpec`` class, which represents the navigation\nstructure defined by the user in the doc-forge navigation specification\n(typically ``docforge.nav.yml``).", "docstring": "This module defines the NavSpec class, which represents the user's intent for\ndocumentation navigation as defined in a YAML specification (usually\ndocforge.nav.yml).",
"objects": { "objects": {
"Path": { "Path": {
"name": "Path", "name": "Path",
@@ -43,8 +43,8 @@
"name": "NavSpec", "name": "NavSpec",
"kind": "class", "kind": "class",
"path": "docforge.nav.spec.NavSpec", "path": "docforge.nav.spec.NavSpec",
"signature": "<bound method Class.signature of Class('NavSpec', 15, 104)>", "signature": "<bound method Class.signature of Class('NavSpec', 13, 91)>",
"docstring": "Parsed representation of a navigation specification.\n\nA ``NavSpec`` describes the intended documentation navigation layout before\nit is resolved against the filesystem.\n\nAttributes:\n home: Relative path to the documentation home page (for example\n ``index.md``).\n groups: Mapping of navigation group titles to lists of file patterns\n or glob expressions.", "docstring": "Parsed representation of the docforge navigation specification file.\n\nAttributes:\n home: Path to the home document (e.g., 'index.md').\n groups: Mapping of group titles to lists of path patterns/globs.",
"members": { "members": {
"home": { "home": {
"name": "home", "name": "home",
@@ -64,15 +64,15 @@
"name": "load", "name": "load",
"kind": "function", "kind": "function",
"path": "docforge.nav.spec.NavSpec.load", "path": "docforge.nav.spec.NavSpec.load",
"signature": "<bound method Function.signature of Function('load', 45, 86)>", "signature": "<bound method Function.signature of Function('load', 37, 77)>",
"docstring": "Load a navigation specification from a YAML file.\n\nArgs:\n path: Filesystem path to the navigation specification file.\n\nReturns:\n A ``NavSpec`` instance representing the parsed configuration.\n\nRaises:\n FileNotFoundError: If the specified file does not exist.\n ValueError: If the file contents are not a valid navigation\n specification." "docstring": "Load a NavSpec from a YAML file.\n\nArgs:\n path: The filesystem path to the YAML file.\n\nReturns:\n A NavSpec instance.\n\nRaises:\n FileNotFoundError: If the path does not exist.\n ValueError: If the file content is not a valid NavSpec mapping."
}, },
"all_patterns": { "all_patterns": {
"name": "all_patterns", "name": "all_patterns",
"kind": "function", "kind": "function",
"path": "docforge.nav.spec.NavSpec.all_patterns", "path": "docforge.nav.spec.NavSpec.all_patterns",
"signature": "<bound method Function.signature of Function('all_patterns', 88, 104)>", "signature": "<bound method Function.signature of Function('all_patterns', 79, 91)>",
"docstring": "Return all path patterns referenced by the specification.\n\nReturns:\n A list containing the home document (if defined) and all\n group pattern entries." "docstring": "Get all path patterns referenced in the specification.\n\nReturns:\n A list of all patterns (home plus all groups)."
} }
} }
}, },
@@ -80,8 +80,8 @@
"name": "load_nav_spec", "name": "load_nav_spec",
"kind": "function", "kind": "function",
"path": "docforge.nav.spec.load_nav_spec", "path": "docforge.nav.spec.load_nav_spec",
"signature": "<bound method Function.signature of Function('load_nav_spec', 107, 135)>", "signature": "<bound method Function.signature of Function('load_nav_spec', 94, 114)>",
"docstring": "Load a navigation specification file.\n\nThis helper function reads a YAML navigation file and constructs a\ncorresponding ``NavSpec`` instance.\n\nArgs:\n path: Path to the navigation specification file.\n\nReturns:\n A ``NavSpec`` instance representing the parsed specification.\n\nRaises:\n FileNotFoundError: If the specification file does not exist.\n ValueError: If the YAML structure is invalid." "docstring": "Utility function to load a NavSpec from a file.\n\nArgs:\n path: Path to the navigation specification file.\n\nReturns:\n A loaded NavSpec instance."
} }
} }
} }

24
mcp_docs/modules/docforge.renderers.base.json
View File

@@ -2,7 +2,7 @@
"module": "docforge.renderers.base", "module": "docforge.renderers.base",
"content": { "content": {
"path": "docforge.renderers.base", "path": "docforge.renderers.base",
"docstring": "# Summary\n\nRenderer base interfaces and configuration models.\n\nThis module defines the base protocol and configuration container used by\ndoc-forge renderers. Concrete renderer implementations should implement the\n`DocRenderer` protocol.", "docstring": "This module defines the base interfaces and configuration containers for\ndoc-forge renderers. All renderer implementations should adhere to the\nDocRenderer protocol.",
"objects": { "objects": {
"Path": { "Path": {
"name": "Path", "name": "Path",
@@ -23,7 +23,7 @@
"kind": "class", "kind": "class",
"path": "docforge.renderers.base.Project", "path": "docforge.renderers.base.Project",
"signature": "<bound method Alias.signature of Alias('Project', 'docforge.models.Project')>", "signature": "<bound method Alias.signature of Alias('Project', 'docforge.models.Project')>",
"docstring": "Representation of a documentation project.\n\nA `Project` serves as the root container for all modules discovered during\nintrospection. Each module is stored by its dotted import path.\n\nAttributes:\n name (str):\n Name of the project.\n\n modules (Dict[str, Module]):\n Mapping of module paths to `Module` instances.", "docstring": "Represents a documentation project, serving as a container for modules.\n\nAttributes:\n name: Name of the project.\n modules: Dictionary mapping module paths to Module instances.",
"members": { "members": {
"name": { "name": {
"name": "name", "name": "name",
@@ -44,28 +44,28 @@
"kind": "function", "kind": "function",
"path": "docforge.renderers.base.Project.add_module", "path": "docforge.renderers.base.Project.add_module",
"signature": "<bound method Alias.signature of Alias('add_module', 'docforge.models.project.Project.add_module')>", "signature": "<bound method Alias.signature of Alias('add_module', 'docforge.models.project.Project.add_module')>",
"docstring": "Register a module in the project.\n\nArgs:\n module (Module):\n Module instance to add to the project." "docstring": "Add a module to the project.\n\nArgs:\n module: The module to add."
}, },
"get_module": { "get_module": {
"name": "get_module", "name": "get_module",
"kind": "function", "kind": "function",
"path": "docforge.renderers.base.Project.get_module", "path": "docforge.renderers.base.Project.get_module",
"signature": "<bound method Alias.signature of Alias('get_module', 'docforge.models.project.Project.get_module')>", "signature": "<bound method Alias.signature of Alias('get_module', 'docforge.models.project.Project.get_module')>",
"docstring": "Retrieve a module by its dotted path.\n\nArgs:\n path (str):\n Fully qualified dotted module path (for example `pkg.module`).\n\nReturns:\n Module:\n The corresponding `Module` instance.\n\nRaises:\n KeyError:\n If the module does not exist in the project." "docstring": "Retrieve a module by its dotted path.\n\nArgs:\n path: The dotted path of the module (e.g., 'pkg.mod').\n\nReturns:\n The requested Module."
}, },
"get_all_modules": { "get_all_modules": {
"name": "get_all_modules", "name": "get_all_modules",
"kind": "function", "kind": "function",
"path": "docforge.renderers.base.Project.get_all_modules", "path": "docforge.renderers.base.Project.get_all_modules",
"signature": "<bound method Alias.signature of Alias('get_all_modules', 'docforge.models.project.Project.get_all_modules')>", "signature": "<bound method Alias.signature of Alias('get_all_modules', 'docforge.models.project.Project.get_all_modules')>",
"docstring": "Return all modules contained in the project.\n\nReturns:\n Iterable[Module]:\n An iterable of `Module` instances." "docstring": "Get all modules in the project.\n\nReturns:\n An iterable of Module objects."
}, },
"get_module_list": { "get_module_list": {
"name": "get_module_list", "name": "get_module_list",
"kind": "function", "kind": "function",
"path": "docforge.renderers.base.Project.get_module_list", "path": "docforge.renderers.base.Project.get_module_list",
"signature": "<bound method Alias.signature of Alias('get_module_list', 'docforge.models.project.Project.get_module_list')>", "signature": "<bound method Alias.signature of Alias('get_module_list', 'docforge.models.project.Project.get_module_list')>",
"docstring": "Return the list of module import paths.\n\nReturns:\n list[str]:\n A list containing the dotted paths of all modules in the project." "docstring": "Get the list of all module dotted paths.\n\nReturns:\n A list of module paths."
} }
} }
}, },
@@ -73,8 +73,8 @@
"name": "RendererConfig", "name": "RendererConfig",
"kind": "class", "kind": "class",
"path": "docforge.renderers.base.RendererConfig", "path": "docforge.renderers.base.RendererConfig",
"signature": "<bound method Class.signature of Class('RendererConfig', 17, 44)>", "signature": "<bound method Class.signature of Class('RendererConfig', 13, 24)>",
"docstring": "Configuration container for documentation renderers.\n\nA `RendererConfig` instance groups together the project model and the\noutput directory used during rendering.\n\nAttributes:\n out_dir (Path):\n Directory where generated documentation files will be written.\n\n project (Project):\n Documentation project model to be rendered.", "docstring": "Configuration container for documentation renderers.\n\nArgs:\n out_dir: The directory where documentation files should be written.\n project: The introspected project models to be rendered.",
"members": { "members": {
"out_dir": { "out_dir": {
"name": "out_dir", "name": "out_dir",
@@ -96,8 +96,8 @@
"name": "DocRenderer", "name": "DocRenderer",
"kind": "class", "kind": "class",
"path": "docforge.renderers.base.DocRenderer", "path": "docforge.renderers.base.DocRenderer",
"signature": "<bound method Class.signature of Class('DocRenderer', 47, 72)>", "signature": "<bound method Class.signature of Class('DocRenderer', 27, 46)>",
"docstring": "Protocol defining the interface for documentation renderers.\n\nImplementations of this protocol are responsible for transforming a\n`Project` model into renderer-specific documentation sources.", "docstring": "Protocol defining the interface for documentation renderers.",
"members": { "members": {
"name": { "name": {
"name": "name", "name": "name",
@@ -110,8 +110,8 @@
"name": "generate_sources", "name": "generate_sources",
"kind": "function", "kind": "function",
"path": "docforge.renderers.base.DocRenderer.generate_sources", "path": "docforge.renderers.base.DocRenderer.generate_sources",
"signature": "<bound method Function.signature of Function('generate_sources', 57, 72)>", "signature": "<bound method Function.signature of Function('generate_sources', 34, 46)>",
"docstring": "Generate renderer-specific documentation sources.\n\nArgs:\n project (Project):\n Project model containing modules and documentation objects.\n\n out_dir (Path):\n Directory where generated documentation sources should be written." "docstring": "Generate renderer-specific source files for the given project.\n\nArgs:\n project: The project models containing modules and objects.\n out_dir: Target directory for the generated files."
} }
} }
} }

157
mcp_docs/modules/docforge.renderers.json
View File

@@ -2,14 +2,14 @@
"module": "docforge.renderers", "module": "docforge.renderers",
"content": { "content": {
"path": "docforge.renderers", "path": "docforge.renderers",
"docstring": "# Summary\n\nRenderers layer for doc-forge.\n\nThe `docforge.renderers` package transforms the internal documentation\nmodels into files formatted for specific documentation systems.\n\n---\n\n# Overview\n\nRenderers consume the doc-forge project model and generate output suitable\nfor documentation tools or machine interfaces.\n\nCurrent implementations:\n\n- **MkDocsRenderer** – Produces Markdown files compatible with MkDocs and\n the `mkdocstrings` plugin. It automatically handles package hierarchy\n and generates `index.md` files for packages.\n- **MCPRenderer** – Emits structured JSON resources designed for consumption\n by Model Context Protocol (MCP) clients.\n\n---\n\n# Extending\n\nNew renderers can be added by implementing the `DocRenderer` protocol\ndefined in `docforge.renderers.base`.\n\n---", "docstring": "# Renderers Layer\n\nThe `docforge.renderers` package handles the transformation of the internal\ndocumentation models into physical files formatted for specific documentation\nengines.\n\n## Current Implementations\n\n- **MkDocsRenderer**: Generates Markdown files utilizing the `mkdocstrings`\n syntax. It automatically handles package/module hierarchy and generates\n `index.md` files for packages.\n\n## Extending\n\nTo add a new renderer, implement the `DocRenderer` protocol defined in\n`docforge.renderers.base`.",
"objects": { "objects": {
"MkDocsRenderer": { "MkDocsRenderer": {
"name": "MkDocsRenderer", "name": "MkDocsRenderer",
"kind": "class", "kind": "class",
"path": "docforge.renderers.MkDocsRenderer", "path": "docforge.renderers.MkDocsRenderer",
"signature": "<bound method Alias.signature of Alias('MkDocsRenderer', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer')>", "signature": "<bound method Alias.signature of Alias('MkDocsRenderer', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer')>",
"docstring": "Renderer that produces Markdown documentation for MkDocs.\n\nGenerated pages use mkdocstrings directives to reference Python modules,\nallowing MkDocs to render API documentation dynamically.", "docstring": "Renderer that generates Markdown source files formatted for the MkDocs\n'mkdocstrings' plugin.",
"members": { "members": {
"name": { "name": {
"name": "name", "name": "name",
@@ -23,14 +23,7 @@
"kind": "function", "kind": "function",
"path": "docforge.renderers.MkDocsRenderer.generate_sources", "path": "docforge.renderers.MkDocsRenderer.generate_sources",
"signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources')>", "signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources')>",
"docstring": "Generate Markdown documentation files for a project.\n\nThis method renders a documentation structure from the provided\nproject model and writes the resulting Markdown files to the\nspecified output directory.\n\nArgs:\n project (Project):\n Project model containing modules to document.\n\n out_dir (Path):\n Directory where generated Markdown files will be written.\n\n module_is_source (bool, optional):\n If True, treat the specified module as the documentation root\n rather than nesting it inside a folder." "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."
},
"generate_readme": {
"name": "generate_readme",
"kind": "function",
"path": "docforge.renderers.MkDocsRenderer.generate_readme",
"signature": "<bound method Alias.signature of Alias('generate_readme', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_readme')>",
"docstring": "Generate a `README.md` file from the root module docstring.\n\nBehavior:\n\n- If `module_is_source` is True, `README.md` is written to the project\n root directory.\n- If False, README generation is currently not implemented.\n\nArgs:\n project (Project):\n Project model containing documentation metadata.\n\n docs_dir (Path):\n Directory containing generated documentation sources.\n\n module_is_source (bool, optional):\n Whether the module is treated as the project source root."
} }
} }
}, },
@@ -39,7 +32,7 @@
"kind": "class", "kind": "class",
"path": "docforge.renderers.MCPRenderer", "path": "docforge.renderers.MCPRenderer",
"signature": "<bound method Alias.signature of Alias('MCPRenderer', 'docforge.renderers.mcp_renderer.MCPRenderer')>", "signature": "<bound method Alias.signature of Alias('MCPRenderer', 'docforge.renderers.mcp_renderer.MCPRenderer')>",
"docstring": "Renderer that generates MCP-compatible documentation resources.\n\nThis renderer converts doc-forge project models into structured JSON\nresources suitable for consumption by systems implementing the Model\nContext Protocol (MCP).", "docstring": "Renderer that emits MCP-native JSON resources from docforge models.",
"members": { "members": {
"name": { "name": {
"name": "name", "name": "name",
@@ -53,7 +46,7 @@
"kind": "function", "kind": "function",
"path": "docforge.renderers.MCPRenderer.generate_sources", "path": "docforge.renderers.MCPRenderer.generate_sources",
"signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mcp_renderer.MCPRenderer.generate_sources')>", "signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mcp_renderer.MCPRenderer.generate_sources')>",
"docstring": "Generate MCP documentation resources for a project.\n\nThe renderer serializes each module into a JSON resource and produces\nsupporting metadata files such as `nav.json` and `index.json`.\n\nArgs:\n project (Project):\n Documentation project model to render.\n\n out_dir (Path):\n Directory where MCP resources will be written." "docstring": "Generate MCP-compatible JSON resources and navigation for the project.\n\nArgs:\n project: The project model to render.\n out_dir: Target directory for the generated JSON files."
} }
} }
}, },
@@ -62,7 +55,7 @@
"kind": "module", "kind": "module",
"path": "docforge.renderers.base", "path": "docforge.renderers.base",
"signature": null, "signature": null,
"docstring": "# Summary\n\nRenderer base interfaces and configuration models.\n\nThis module defines the base protocol and configuration container used by\ndoc-forge renderers. Concrete renderer implementations should implement the\n`DocRenderer` protocol.", "docstring": "This module defines the base interfaces and configuration containers for\ndoc-forge renderers. All renderer implementations should adhere to the\nDocRenderer protocol.",
"members": { "members": {
"Path": { "Path": {
"name": "Path", "name": "Path",
@@ -83,7 +76,7 @@
"kind": "class", "kind": "class",
"path": "docforge.renderers.base.Project", "path": "docforge.renderers.base.Project",
"signature": "<bound method Alias.signature of Alias('Project', 'docforge.models.Project')>", "signature": "<bound method Alias.signature of Alias('Project', 'docforge.models.Project')>",
"docstring": "Representation of a documentation project.\n\nA `Project` serves as the root container for all modules discovered during\nintrospection. Each module is stored by its dotted import path.\n\nAttributes:\n name (str):\n Name of the project.\n\n modules (Dict[str, Module]):\n Mapping of module paths to `Module` instances.", "docstring": "Represents a documentation project, serving as a container for modules.\n\nAttributes:\n name: Name of the project.\n modules: Dictionary mapping module paths to Module instances.",
"members": { "members": {
"name": { "name": {
"name": "name", "name": "name",
@@ -104,28 +97,28 @@
"kind": "function", "kind": "function",
"path": "docforge.renderers.base.Project.add_module", "path": "docforge.renderers.base.Project.add_module",
"signature": "<bound method Alias.signature of Alias('add_module', 'docforge.models.project.Project.add_module')>", "signature": "<bound method Alias.signature of Alias('add_module', 'docforge.models.project.Project.add_module')>",
"docstring": "Register a module in the project.\n\nArgs:\n module (Module):\n Module instance to add to the project." "docstring": "Add a module to the project.\n\nArgs:\n module: The module to add."
}, },
"get_module": { "get_module": {
"name": "get_module", "name": "get_module",
"kind": "function", "kind": "function",
"path": "docforge.renderers.base.Project.get_module", "path": "docforge.renderers.base.Project.get_module",
"signature": "<bound method Alias.signature of Alias('get_module', 'docforge.models.project.Project.get_module')>", "signature": "<bound method Alias.signature of Alias('get_module', 'docforge.models.project.Project.get_module')>",
"docstring": "Retrieve a module by its dotted path.\n\nArgs:\n path (str):\n Fully qualified dotted module path (for example `pkg.module`).\n\nReturns:\n Module:\n The corresponding `Module` instance.\n\nRaises:\n KeyError:\n If the module does not exist in the project." "docstring": "Retrieve a module by its dotted path.\n\nArgs:\n path: The dotted path of the module (e.g., 'pkg.mod').\n\nReturns:\n The requested Module."
}, },
"get_all_modules": { "get_all_modules": {
"name": "get_all_modules", "name": "get_all_modules",
"kind": "function", "kind": "function",
"path": "docforge.renderers.base.Project.get_all_modules", "path": "docforge.renderers.base.Project.get_all_modules",
"signature": "<bound method Alias.signature of Alias('get_all_modules', 'docforge.models.project.Project.get_all_modules')>", "signature": "<bound method Alias.signature of Alias('get_all_modules', 'docforge.models.project.Project.get_all_modules')>",
"docstring": "Return all modules contained in the project.\n\nReturns:\n Iterable[Module]:\n An iterable of `Module` instances." "docstring": "Get all modules in the project.\n\nReturns:\n An iterable of Module objects."
}, },
"get_module_list": { "get_module_list": {
"name": "get_module_list", "name": "get_module_list",
"kind": "function", "kind": "function",
"path": "docforge.renderers.base.Project.get_module_list", "path": "docforge.renderers.base.Project.get_module_list",
"signature": "<bound method Alias.signature of Alias('get_module_list', 'docforge.models.project.Project.get_module_list')>", "signature": "<bound method Alias.signature of Alias('get_module_list', 'docforge.models.project.Project.get_module_list')>",
"docstring": "Return the list of module import paths.\n\nReturns:\n list[str]:\n A list containing the dotted paths of all modules in the project." "docstring": "Get the list of all module dotted paths.\n\nReturns:\n A list of module paths."
} }
} }
}, },
@@ -133,8 +126,8 @@
"name": "RendererConfig", "name": "RendererConfig",
"kind": "class", "kind": "class",
"path": "docforge.renderers.base.RendererConfig", "path": "docforge.renderers.base.RendererConfig",
"signature": "<bound method Class.signature of Class('RendererConfig', 17, 44)>", "signature": "<bound method Class.signature of Class('RendererConfig', 13, 24)>",
"docstring": "Configuration container for documentation renderers.\n\nA `RendererConfig` instance groups together the project model and the\noutput directory used during rendering.\n\nAttributes:\n out_dir (Path):\n Directory where generated documentation files will be written.\n\n project (Project):\n Documentation project model to be rendered.", "docstring": "Configuration container for documentation renderers.\n\nArgs:\n out_dir: The directory where documentation files should be written.\n project: The introspected project models to be rendered.",
"members": { "members": {
"out_dir": { "out_dir": {
"name": "out_dir", "name": "out_dir",
@@ -156,8 +149,8 @@
"name": "DocRenderer", "name": "DocRenderer",
"kind": "class", "kind": "class",
"path": "docforge.renderers.base.DocRenderer", "path": "docforge.renderers.base.DocRenderer",
"signature": "<bound method Class.signature of Class('DocRenderer', 47, 72)>", "signature": "<bound method Class.signature of Class('DocRenderer', 27, 46)>",
"docstring": "Protocol defining the interface for documentation renderers.\n\nImplementations of this protocol are responsible for transforming a\n`Project` model into renderer-specific documentation sources.", "docstring": "Protocol defining the interface for documentation renderers.",
"members": { "members": {
"name": { "name": {
"name": "name", "name": "name",
@@ -170,8 +163,8 @@
"name": "generate_sources", "name": "generate_sources",
"kind": "function", "kind": "function",
"path": "docforge.renderers.base.DocRenderer.generate_sources", "path": "docforge.renderers.base.DocRenderer.generate_sources",
"signature": "<bound method Function.signature of Function('generate_sources', 57, 72)>", "signature": "<bound method Function.signature of Function('generate_sources', 34, 46)>",
"docstring": "Generate renderer-specific documentation sources.\n\nArgs:\n project (Project):\n Project model containing modules and documentation objects.\n\n out_dir (Path):\n Directory where generated documentation sources should be written." "docstring": "Generate renderer-specific source files for the given project.\n\nArgs:\n project: The project models containing modules and objects.\n out_dir: Target directory for the generated files."
} }
} }
} }
@@ -182,7 +175,7 @@
"kind": "module", "kind": "module",
"path": "docforge.renderers.mcp_renderer", "path": "docforge.renderers.mcp_renderer",
"signature": null, "signature": null,
"docstring": "# Summary\n\nMCP renderer implementation.\n\nThis module defines the `MCPRenderer` class, which generates documentation\nresources compatible with the Model Context Protocol (MCP).", "docstring": null,
"members": { "members": {
"json": { "json": {
"name": "json", "name": "json",
@@ -217,7 +210,7 @@
"kind": "class", "kind": "class",
"path": "docforge.renderers.mcp_renderer.Project", "path": "docforge.renderers.mcp_renderer.Project",
"signature": "<bound method Alias.signature of Alias('Project', 'docforge.models.Project')>", "signature": "<bound method Alias.signature of Alias('Project', 'docforge.models.Project')>",
"docstring": "Representation of a documentation project.\n\nA `Project` serves as the root container for all modules discovered during\nintrospection. Each module is stored by its dotted import path.\n\nAttributes:\n name (str):\n Name of the project.\n\n modules (Dict[str, Module]):\n Mapping of module paths to `Module` instances.", "docstring": "Represents a documentation project, serving as a container for modules.\n\nAttributes:\n name: Name of the project.\n modules: Dictionary mapping module paths to Module instances.",
"members": { "members": {
"name": { "name": {
"name": "name", "name": "name",
@@ -238,28 +231,28 @@
"kind": "function", "kind": "function",
"path": "docforge.renderers.mcp_renderer.Project.add_module", "path": "docforge.renderers.mcp_renderer.Project.add_module",
"signature": "<bound method Alias.signature of Alias('add_module', 'docforge.models.project.Project.add_module')>", "signature": "<bound method Alias.signature of Alias('add_module', 'docforge.models.project.Project.add_module')>",
"docstring": "Register a module in the project.\n\nArgs:\n module (Module):\n Module instance to add to the project." "docstring": "Add a module to the project.\n\nArgs:\n module: The module to add."
}, },
"get_module": { "get_module": {
"name": "get_module", "name": "get_module",
"kind": "function", "kind": "function",
"path": "docforge.renderers.mcp_renderer.Project.get_module", "path": "docforge.renderers.mcp_renderer.Project.get_module",
"signature": "<bound method Alias.signature of Alias('get_module', 'docforge.models.project.Project.get_module')>", "signature": "<bound method Alias.signature of Alias('get_module', 'docforge.models.project.Project.get_module')>",
"docstring": "Retrieve a module by its dotted path.\n\nArgs:\n path (str):\n Fully qualified dotted module path (for example `pkg.module`).\n\nReturns:\n Module:\n The corresponding `Module` instance.\n\nRaises:\n KeyError:\n If the module does not exist in the project." "docstring": "Retrieve a module by its dotted path.\n\nArgs:\n path: The dotted path of the module (e.g., 'pkg.mod').\n\nReturns:\n The requested Module."
}, },
"get_all_modules": { "get_all_modules": {
"name": "get_all_modules", "name": "get_all_modules",
"kind": "function", "kind": "function",
"path": "docforge.renderers.mcp_renderer.Project.get_all_modules", "path": "docforge.renderers.mcp_renderer.Project.get_all_modules",
"signature": "<bound method Alias.signature of Alias('get_all_modules', 'docforge.models.project.Project.get_all_modules')>", "signature": "<bound method Alias.signature of Alias('get_all_modules', 'docforge.models.project.Project.get_all_modules')>",
"docstring": "Return all modules contained in the project.\n\nReturns:\n Iterable[Module]:\n An iterable of `Module` instances." "docstring": "Get all modules in the project.\n\nReturns:\n An iterable of Module objects."
}, },
"get_module_list": { "get_module_list": {
"name": "get_module_list", "name": "get_module_list",
"kind": "function", "kind": "function",
"path": "docforge.renderers.mcp_renderer.Project.get_module_list", "path": "docforge.renderers.mcp_renderer.Project.get_module_list",
"signature": "<bound method Alias.signature of Alias('get_module_list', 'docforge.models.project.Project.get_module_list')>", "signature": "<bound method Alias.signature of Alias('get_module_list', 'docforge.models.project.Project.get_module_list')>",
"docstring": "Return the list of module import paths.\n\nReturns:\n list[str]:\n A list containing the dotted paths of all modules in the project." "docstring": "Get the list of all module dotted paths.\n\nReturns:\n A list of module paths."
} }
} }
}, },
@@ -268,7 +261,7 @@
"kind": "class", "kind": "class",
"path": "docforge.renderers.mcp_renderer.Module", "path": "docforge.renderers.mcp_renderer.Module",
"signature": "<bound method Alias.signature of Alias('Module', 'docforge.models.Module')>", "signature": "<bound method Alias.signature of Alias('Module', 'docforge.models.Module')>",
"docstring": "Representation of a documented Python module or package.\n\nA `Module` stores metadata about the module itself and maintains a\ncollection of top-level documentation objects discovered during\nintrospection.\n\nAttributes:\n path (str):\n Dotted import path of the module.\n\n docstring (Optional[str]):\n Module-level documentation string, if present.\n\n members (Dict[str, DocObject]):\n Mapping of object names to their corresponding `DocObject` representations.", "docstring": "Represents a documented Python module or package.\n\nAttributes:\n path: Dotted import path of the module.\n docstring: Module-level docstring content.\n members: Dictionary mapping object names to their DocObject representations.",
"members": { "members": {
"path": { "path": {
"name": "path", "name": "path",
@@ -296,21 +289,21 @@
"kind": "function", "kind": "function",
"path": "docforge.renderers.mcp_renderer.Module.add_object", "path": "docforge.renderers.mcp_renderer.Module.add_object",
"signature": "<bound method Alias.signature of Alias('add_object', 'docforge.models.module.Module.add_object')>", "signature": "<bound method Alias.signature of Alias('add_object', 'docforge.models.module.Module.add_object')>",
"docstring": "Add a documented object to the module.\n\nArgs:\n obj (DocObject):\n Documentation object to register as a top-level member of the module." "docstring": "Add a documented object to the module.\n\nArgs:\n obj: The object to add."
}, },
"get_object": { "get_object": {
"name": "get_object", "name": "get_object",
"kind": "function", "kind": "function",
"path": "docforge.renderers.mcp_renderer.Module.get_object", "path": "docforge.renderers.mcp_renderer.Module.get_object",
"signature": "<bound method Alias.signature of Alias('get_object', 'docforge.models.module.Module.get_object')>", "signature": "<bound method Alias.signature of Alias('get_object', 'docforge.models.module.Module.get_object')>",
"docstring": "Retrieve a documented object by name.\n\nArgs:\n name (str):\n Name of the object to retrieve.\n\nReturns:\n DocObject:\n The corresponding `DocObject` instance.\n\nRaises:\n KeyError:\n If no object with the given name exists." "docstring": "Retrieve a member object by name.\n\nArgs:\n name: The name of the object.\n\nReturns:\n The requested DocObject."
}, },
"get_all_objects": { "get_all_objects": {
"name": "get_all_objects", "name": "get_all_objects",
"kind": "function", "kind": "function",
"path": "docforge.renderers.mcp_renderer.Module.get_all_objects", "path": "docforge.renderers.mcp_renderer.Module.get_all_objects",
"signature": "<bound method Alias.signature of Alias('get_all_objects', 'docforge.models.module.Module.get_all_objects')>", "signature": "<bound method Alias.signature of Alias('get_all_objects', 'docforge.models.module.Module.get_all_objects')>",
"docstring": "Return all top-level documentation objects in the module.\n\nReturns:\n Iterable[DocObject]:\n An iterable of `DocObject` instances representing the module's public members." "docstring": "Get all top-level objects in the module.\n\nReturns:\n An iterable of DocObject instances."
} }
} }
}, },
@@ -319,7 +312,7 @@
"kind": "class", "kind": "class",
"path": "docforge.renderers.mcp_renderer.DocObject", "path": "docforge.renderers.mcp_renderer.DocObject",
"signature": "<bound method Alias.signature of Alias('DocObject', 'docforge.models.DocObject')>", "signature": "<bound method Alias.signature of Alias('DocObject', 'docforge.models.DocObject')>",
"docstring": "Representation of a documented Python object.\n\nA `DocObject` models a single Python entity discovered during\nintrospection. Objects may contain nested members, allowing the structure\nof modules, classes, and other containers to be represented recursively.\n\nAttributes:\n name (str):\n Local name of the object.\n\n kind (str):\n Type of object (for example `class`, `function`, `method`, or `attribute`).\n\n path (str):\n Fully qualified dotted path to the object.\n\n signature (Optional[str]):\n Callable signature if the object represents a callable.\n\n docstring (Optional[str]):\n Raw docstring text extracted from the source code.\n\n members (Dict[str, DocObject]):\n Mapping of member names to child `DocObject` instances.", "docstring": "Represents a documented Python object (class, function, method, etc.).\n\nAttributes:\n name: Local name of the object.\n kind: Type of object (e.g., 'class', 'function', 'attribute').\n path: Full dotted import path to the object.\n signature: Callable signature, if applicable.\n docstring: Raw docstring content extracted from the source.\n members: Dictionary mapping member names to their DocObject representations.",
"members": { "members": {
"name": { "name": {
"name": "name", "name": "name",
@@ -368,21 +361,21 @@
"kind": "function", "kind": "function",
"path": "docforge.renderers.mcp_renderer.DocObject.add_member", "path": "docforge.renderers.mcp_renderer.DocObject.add_member",
"signature": "<bound method Alias.signature of Alias('add_member', 'docforge.models.object.DocObject.add_member')>", "signature": "<bound method Alias.signature of Alias('add_member', 'docforge.models.object.DocObject.add_member')>",
"docstring": "Add a child documentation object.\n\nThis is typically used when attaching methods to classes or\nnested objects to their parent containers.\n\nArgs:\n obj: Documentation object to add as a member." "docstring": "Add a child member to this object (e.g., a method to a class).\n\nArgs:\n obj: The child DocObject to add."
}, },
"get_member": { "get_member": {
"name": "get_member", "name": "get_member",
"kind": "function", "kind": "function",
"path": "docforge.renderers.mcp_renderer.DocObject.get_member", "path": "docforge.renderers.mcp_renderer.DocObject.get_member",
"signature": "<bound method Alias.signature of Alias('get_member', 'docforge.models.object.DocObject.get_member')>", "signature": "<bound method Alias.signature of Alias('get_member', 'docforge.models.object.DocObject.get_member')>",
"docstring": "Retrieve a member object by name.\n\nArgs:\n name (str):\n Name of the member to retrieve.\n\nReturns:\n DocObject:\n The corresponding `DocObject` instance.\n\nRaises:\n KeyError:\n If the member does not exist." "docstring": "Retrieve a child member by name.\n\nArgs:\n name: The name of the member.\n\nReturns:\n The requested DocObject."
}, },
"get_all_members": { "get_all_members": {
"name": "get_all_members", "name": "get_all_members",
"kind": "function", "kind": "function",
"path": "docforge.renderers.mcp_renderer.DocObject.get_all_members", "path": "docforge.renderers.mcp_renderer.DocObject.get_all_members",
"signature": "<bound method Alias.signature of Alias('get_all_members', 'docforge.models.object.DocObject.get_all_members')>", "signature": "<bound method Alias.signature of Alias('get_all_members', 'docforge.models.object.DocObject.get_all_members')>",
"docstring": "Return all child members of the object.\n\nReturns:\n Iterable[DocObject]:\n An iterable of `DocObject` instances representing nested members." "docstring": "Get all members of this object.\n\nReturns:\n An iterable of child DocObject instances."
} }
} }
}, },
@@ -390,8 +383,8 @@
"name": "MCPRenderer", "name": "MCPRenderer",
"kind": "class", "kind": "class",
"path": "docforge.renderers.mcp_renderer.MCPRenderer", "path": "docforge.renderers.mcp_renderer.MCPRenderer",
"signature": "<bound method Class.signature of Class('MCPRenderer', 17, 159)>", "signature": "<bound method Class.signature of Class('MCPRenderer', 8, 122)>",
"docstring": "Renderer that generates MCP-compatible documentation resources.\n\nThis renderer converts doc-forge project models into structured JSON\nresources suitable for consumption by systems implementing the Model\nContext Protocol (MCP).", "docstring": "Renderer that emits MCP-native JSON resources from docforge models.",
"members": { "members": {
"name": { "name": {
"name": "name", "name": "name",
@@ -404,8 +397,8 @@
"name": "generate_sources", "name": "generate_sources",
"kind": "function", "kind": "function",
"path": "docforge.renderers.mcp_renderer.MCPRenderer.generate_sources", "path": "docforge.renderers.mcp_renderer.MCPRenderer.generate_sources",
"signature": "<bound method Function.signature of Function('generate_sources', 28, 72)>", "signature": "<bound method Function.signature of Function('generate_sources', 15, 53)>",
"docstring": "Generate MCP documentation resources for a project.\n\nThe renderer serializes each module into a JSON resource and produces\nsupporting metadata files such as `nav.json` and `index.json`.\n\nArgs:\n project (Project):\n Documentation project model to render.\n\n out_dir (Path):\n Directory where MCP resources will be written." "docstring": "Generate MCP-compatible JSON resources and navigation for the project.\n\nArgs:\n project: The project model to render.\n out_dir: Target directory for the generated JSON files."
} }
} }
} }
@@ -416,7 +409,7 @@
"kind": "module", "kind": "module",
"path": "docforge.renderers.mkdocs_renderer", "path": "docforge.renderers.mkdocs_renderer",
"signature": null, "signature": null,
"docstring": "# Summary\n\nMkDocs renderer implementation.\n\nThis module defines the `MkDocsRenderer` class, which generates Markdown\ndocumentation sources compatible with MkDocs Material and the mkdocstrings\nplugin.\n\nThe renderer ensures a consistent documentation structure by:\n\n- Creating a root `index.md` if one does not exist\n- Generating package index pages automatically\n- Linking child modules within parent package pages\n- Optionally generating `README.md` from the root package docstring", "docstring": "This module implements the MkDocsRenderer, which generates Markdown source files\ncompatible with the MkDocs 'material' theme and 'mkdocstrings' extension.",
"members": { "members": {
"Path": { "Path": {
"name": "Path", "name": "Path",
@@ -430,7 +423,7 @@
"kind": "class", "kind": "class",
"path": "docforge.renderers.mkdocs_renderer.Project", "path": "docforge.renderers.mkdocs_renderer.Project",
"signature": "<bound method Alias.signature of Alias('Project', 'docforge.models.Project')>", "signature": "<bound method Alias.signature of Alias('Project', 'docforge.models.Project')>",
"docstring": "Representation of a documentation project.\n\nA `Project` serves as the root container for all modules discovered during\nintrospection. Each module is stored by its dotted import path.\n\nAttributes:\n name (str):\n Name of the project.\n\n modules (Dict[str, Module]):\n Mapping of module paths to `Module` instances.", "docstring": "Represents a documentation project, serving as a container for modules.\n\nAttributes:\n name: Name of the project.\n modules: Dictionary mapping module paths to Module instances.",
"members": { "members": {
"name": { "name": {
"name": "name", "name": "name",
@@ -451,37 +444,67 @@
"kind": "function", "kind": "function",
"path": "docforge.renderers.mkdocs_renderer.Project.add_module", "path": "docforge.renderers.mkdocs_renderer.Project.add_module",
"signature": "<bound method Alias.signature of Alias('add_module', 'docforge.models.project.Project.add_module')>", "signature": "<bound method Alias.signature of Alias('add_module', 'docforge.models.project.Project.add_module')>",
"docstring": "Register a module in the project.\n\nArgs:\n module (Module):\n Module instance to add to the project." "docstring": "Add a module to the project.\n\nArgs:\n module: The module to add."
}, },
"get_module": { "get_module": {
"name": "get_module", "name": "get_module",
"kind": "function", "kind": "function",
"path": "docforge.renderers.mkdocs_renderer.Project.get_module", "path": "docforge.renderers.mkdocs_renderer.Project.get_module",
"signature": "<bound method Alias.signature of Alias('get_module', 'docforge.models.project.Project.get_module')>", "signature": "<bound method Alias.signature of Alias('get_module', 'docforge.models.project.Project.get_module')>",
"docstring": "Retrieve a module by its dotted path.\n\nArgs:\n path (str):\n Fully qualified dotted module path (for example `pkg.module`).\n\nReturns:\n Module:\n The corresponding `Module` instance.\n\nRaises:\n KeyError:\n If the module does not exist in the project." "docstring": "Retrieve a module by its dotted path.\n\nArgs:\n path: The dotted path of the module (e.g., 'pkg.mod').\n\nReturns:\n The requested Module."
}, },
"get_all_modules": { "get_all_modules": {
"name": "get_all_modules", "name": "get_all_modules",
"kind": "function", "kind": "function",
"path": "docforge.renderers.mkdocs_renderer.Project.get_all_modules", "path": "docforge.renderers.mkdocs_renderer.Project.get_all_modules",
"signature": "<bound method Alias.signature of Alias('get_all_modules', 'docforge.models.project.Project.get_all_modules')>", "signature": "<bound method Alias.signature of Alias('get_all_modules', 'docforge.models.project.Project.get_all_modules')>",
"docstring": "Return all modules contained in the project.\n\nReturns:\n Iterable[Module]:\n An iterable of `Module` instances." "docstring": "Get all modules in the project.\n\nReturns:\n An iterable of Module objects."
}, },
"get_module_list": { "get_module_list": {
"name": "get_module_list", "name": "get_module_list",
"kind": "function", "kind": "function",
"path": "docforge.renderers.mkdocs_renderer.Project.get_module_list", "path": "docforge.renderers.mkdocs_renderer.Project.get_module_list",
"signature": "<bound method Alias.signature of Alias('get_module_list', 'docforge.models.project.Project.get_module_list')>", "signature": "<bound method Alias.signature of Alias('get_module_list', 'docforge.models.project.Project.get_module_list')>",
"docstring": "Return the list of module import paths.\n\nReturns:\n list[str]:\n A list containing the dotted paths of all modules in the project." "docstring": "Get the list of all module dotted paths.\n\nReturns:\n A list of module paths."
} }
} }
}, },
"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": { "Module": {
"name": "Module", "name": "Module",
"kind": "class", "kind": "class",
"path": "docforge.renderers.mkdocs_renderer.Module", "path": "docforge.renderers.mkdocs_renderer.Module",
"signature": "<bound method Alias.signature of Alias('Module', 'docforge.models.Module')>", "signature": "<bound method Alias.signature of Alias('Module', 'docforge.models.Module')>",
"docstring": "Representation of a documented Python module or package.\n\nA `Module` stores metadata about the module itself and maintains a\ncollection of top-level documentation objects discovered during\nintrospection.\n\nAttributes:\n path (str):\n Dotted import path of the module.\n\n docstring (Optional[str]):\n Module-level documentation string, if present.\n\n members (Dict[str, DocObject]):\n Mapping of object names to their corresponding `DocObject` representations.", "docstring": "Represents a documented Python module or package.\n\nAttributes:\n path: Dotted import path of the module.\n docstring: Module-level docstring content.\n members: Dictionary mapping object names to their DocObject representations.",
"members": { "members": {
"path": { "path": {
"name": "path", "name": "path",
@@ -509,51 +532,21 @@
"kind": "function", "kind": "function",
"path": "docforge.renderers.mkdocs_renderer.Module.add_object", "path": "docforge.renderers.mkdocs_renderer.Module.add_object",
"signature": "<bound method Alias.signature of Alias('add_object', 'docforge.models.module.Module.add_object')>", "signature": "<bound method Alias.signature of Alias('add_object', 'docforge.models.module.Module.add_object')>",
"docstring": "Add a documented object to the module.\n\nArgs:\n obj (DocObject):\n Documentation object to register as a top-level member of the module." "docstring": "Add a documented object to the module.\n\nArgs:\n obj: The object to add."
}, },
"get_object": { "get_object": {
"name": "get_object", "name": "get_object",
"kind": "function", "kind": "function",
"path": "docforge.renderers.mkdocs_renderer.Module.get_object", "path": "docforge.renderers.mkdocs_renderer.Module.get_object",
"signature": "<bound method Alias.signature of Alias('get_object', 'docforge.models.module.Module.get_object')>", "signature": "<bound method Alias.signature of Alias('get_object', 'docforge.models.module.Module.get_object')>",
"docstring": "Retrieve a documented object by name.\n\nArgs:\n name (str):\n Name of the object to retrieve.\n\nReturns:\n DocObject:\n The corresponding `DocObject` instance.\n\nRaises:\n KeyError:\n If no object with the given name exists." "docstring": "Retrieve a member object by name.\n\nArgs:\n name: The name of the object.\n\nReturns:\n The requested DocObject."
}, },
"get_all_objects": { "get_all_objects": {
"name": "get_all_objects", "name": "get_all_objects",
"kind": "function", "kind": "function",
"path": "docforge.renderers.mkdocs_renderer.Module.get_all_objects", "path": "docforge.renderers.mkdocs_renderer.Module.get_all_objects",
"signature": "<bound method Alias.signature of Alias('get_all_objects', 'docforge.models.module.Module.get_all_objects')>", "signature": "<bound method Alias.signature of Alias('get_all_objects', 'docforge.models.module.Module.get_all_objects')>",
"docstring": "Return all top-level documentation objects in the module.\n\nReturns:\n Iterable[DocObject]:\n An iterable of `DocObject` instances representing the module's public members." "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', 22, 305)>",
"docstring": "Renderer that produces Markdown documentation for MkDocs.\n\nGenerated pages use mkdocstrings directives to reference Python modules,\nallowing MkDocs to render API documentation dynamically.",
"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', 36, 78)>",
"docstring": "Generate Markdown documentation files for a project.\n\nThis method renders a documentation structure from the provided\nproject model and writes the resulting Markdown files to the\nspecified output directory.\n\nArgs:\n project (Project):\n Project model containing modules to document.\n\n out_dir (Path):\n Directory where generated Markdown files will be written.\n\n module_is_source (bool, optional):\n If True, treat the specified module as the documentation root\n rather than nesting it inside a folder."
},
"generate_readme": {
"name": "generate_readme",
"kind": "function",
"path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_readme",
"signature": "<bound method Function.signature of Function('generate_readme', 80, 139)>",
"docstring": "Generate a `README.md` file from the root module docstring.\n\nBehavior:\n\n- If `module_is_source` is True, `README.md` is written to the project\n root directory.\n- If False, README generation is currently not implemented.\n\nArgs:\n project (Project):\n Project model containing documentation metadata.\n\n docs_dir (Path):\n Directory containing generated documentation sources.\n\n module_is_source (bool, optional):\n Whether the module is treated as the project source root."
} }
} }
} }

36
mcp_docs/modules/docforge.renderers.mcp_renderer.json
View File

@@ -2,7 +2,7 @@
"module": "docforge.renderers.mcp_renderer", "module": "docforge.renderers.mcp_renderer",
"content": { "content": {
"path": "docforge.renderers.mcp_renderer", "path": "docforge.renderers.mcp_renderer",
"docstring": "# Summary\n\nMCP renderer implementation.\n\nThis module defines the `MCPRenderer` class, which generates documentation\nresources compatible with the Model Context Protocol (MCP).", "docstring": null,
"objects": { "objects": {
"json": { "json": {
"name": "json", "name": "json",
@@ -37,7 +37,7 @@
"kind": "class", "kind": "class",
"path": "docforge.renderers.mcp_renderer.Project", "path": "docforge.renderers.mcp_renderer.Project",
"signature": "<bound method Alias.signature of Alias('Project', 'docforge.models.Project')>", "signature": "<bound method Alias.signature of Alias('Project', 'docforge.models.Project')>",
"docstring": "Representation of a documentation project.\n\nA `Project` serves as the root container for all modules discovered during\nintrospection. Each module is stored by its dotted import path.\n\nAttributes:\n name (str):\n Name of the project.\n\n modules (Dict[str, Module]):\n Mapping of module paths to `Module` instances.", "docstring": "Represents a documentation project, serving as a container for modules.\n\nAttributes:\n name: Name of the project.\n modules: Dictionary mapping module paths to Module instances.",
"members": { "members": {
"name": { "name": {
"name": "name", "name": "name",
@@ -58,28 +58,28 @@
"kind": "function", "kind": "function",
"path": "docforge.renderers.mcp_renderer.Project.add_module", "path": "docforge.renderers.mcp_renderer.Project.add_module",
"signature": "<bound method Alias.signature of Alias('add_module', 'docforge.models.project.Project.add_module')>", "signature": "<bound method Alias.signature of Alias('add_module', 'docforge.models.project.Project.add_module')>",
"docstring": "Register a module in the project.\n\nArgs:\n module (Module):\n Module instance to add to the project." "docstring": "Add a module to the project.\n\nArgs:\n module: The module to add."
}, },
"get_module": { "get_module": {
"name": "get_module", "name": "get_module",
"kind": "function", "kind": "function",
"path": "docforge.renderers.mcp_renderer.Project.get_module", "path": "docforge.renderers.mcp_renderer.Project.get_module",
"signature": "<bound method Alias.signature of Alias('get_module', 'docforge.models.project.Project.get_module')>", "signature": "<bound method Alias.signature of Alias('get_module', 'docforge.models.project.Project.get_module')>",
"docstring": "Retrieve a module by its dotted path.\n\nArgs:\n path (str):\n Fully qualified dotted module path (for example `pkg.module`).\n\nReturns:\n Module:\n The corresponding `Module` instance.\n\nRaises:\n KeyError:\n If the module does not exist in the project." "docstring": "Retrieve a module by its dotted path.\n\nArgs:\n path: The dotted path of the module (e.g., 'pkg.mod').\n\nReturns:\n The requested Module."
}, },
"get_all_modules": { "get_all_modules": {
"name": "get_all_modules", "name": "get_all_modules",
"kind": "function", "kind": "function",
"path": "docforge.renderers.mcp_renderer.Project.get_all_modules", "path": "docforge.renderers.mcp_renderer.Project.get_all_modules",
"signature": "<bound method Alias.signature of Alias('get_all_modules', 'docforge.models.project.Project.get_all_modules')>", "signature": "<bound method Alias.signature of Alias('get_all_modules', 'docforge.models.project.Project.get_all_modules')>",
"docstring": "Return all modules contained in the project.\n\nReturns:\n Iterable[Module]:\n An iterable of `Module` instances." "docstring": "Get all modules in the project.\n\nReturns:\n An iterable of Module objects."
}, },
"get_module_list": { "get_module_list": {
"name": "get_module_list", "name": "get_module_list",
"kind": "function", "kind": "function",
"path": "docforge.renderers.mcp_renderer.Project.get_module_list", "path": "docforge.renderers.mcp_renderer.Project.get_module_list",
"signature": "<bound method Alias.signature of Alias('get_module_list', 'docforge.models.project.Project.get_module_list')>", "signature": "<bound method Alias.signature of Alias('get_module_list', 'docforge.models.project.Project.get_module_list')>",
"docstring": "Return the list of module import paths.\n\nReturns:\n list[str]:\n A list containing the dotted paths of all modules in the project." "docstring": "Get the list of all module dotted paths.\n\nReturns:\n A list of module paths."
} }
} }
}, },
@@ -88,7 +88,7 @@
"kind": "class", "kind": "class",
"path": "docforge.renderers.mcp_renderer.Module", "path": "docforge.renderers.mcp_renderer.Module",
"signature": "<bound method Alias.signature of Alias('Module', 'docforge.models.Module')>", "signature": "<bound method Alias.signature of Alias('Module', 'docforge.models.Module')>",
"docstring": "Representation of a documented Python module or package.\n\nA `Module` stores metadata about the module itself and maintains a\ncollection of top-level documentation objects discovered during\nintrospection.\n\nAttributes:\n path (str):\n Dotted import path of the module.\n\n docstring (Optional[str]):\n Module-level documentation string, if present.\n\n members (Dict[str, DocObject]):\n Mapping of object names to their corresponding `DocObject` representations.", "docstring": "Represents a documented Python module or package.\n\nAttributes:\n path: Dotted import path of the module.\n docstring: Module-level docstring content.\n members: Dictionary mapping object names to their DocObject representations.",
"members": { "members": {
"path": { "path": {
"name": "path", "name": "path",
@@ -116,21 +116,21 @@
"kind": "function", "kind": "function",
"path": "docforge.renderers.mcp_renderer.Module.add_object", "path": "docforge.renderers.mcp_renderer.Module.add_object",
"signature": "<bound method Alias.signature of Alias('add_object', 'docforge.models.module.Module.add_object')>", "signature": "<bound method Alias.signature of Alias('add_object', 'docforge.models.module.Module.add_object')>",
"docstring": "Add a documented object to the module.\n\nArgs:\n obj (DocObject):\n Documentation object to register as a top-level member of the module." "docstring": "Add a documented object to the module.\n\nArgs:\n obj: The object to add."
}, },
"get_object": { "get_object": {
"name": "get_object", "name": "get_object",
"kind": "function", "kind": "function",
"path": "docforge.renderers.mcp_renderer.Module.get_object", "path": "docforge.renderers.mcp_renderer.Module.get_object",
"signature": "<bound method Alias.signature of Alias('get_object', 'docforge.models.module.Module.get_object')>", "signature": "<bound method Alias.signature of Alias('get_object', 'docforge.models.module.Module.get_object')>",
"docstring": "Retrieve a documented object by name.\n\nArgs:\n name (str):\n Name of the object to retrieve.\n\nReturns:\n DocObject:\n The corresponding `DocObject` instance.\n\nRaises:\n KeyError:\n If no object with the given name exists." "docstring": "Retrieve a member object by name.\n\nArgs:\n name: The name of the object.\n\nReturns:\n The requested DocObject."
}, },
"get_all_objects": { "get_all_objects": {
"name": "get_all_objects", "name": "get_all_objects",
"kind": "function", "kind": "function",
"path": "docforge.renderers.mcp_renderer.Module.get_all_objects", "path": "docforge.renderers.mcp_renderer.Module.get_all_objects",
"signature": "<bound method Alias.signature of Alias('get_all_objects', 'docforge.models.module.Module.get_all_objects')>", "signature": "<bound method Alias.signature of Alias('get_all_objects', 'docforge.models.module.Module.get_all_objects')>",
"docstring": "Return all top-level documentation objects in the module.\n\nReturns:\n Iterable[DocObject]:\n An iterable of `DocObject` instances representing the module's public members." "docstring": "Get all top-level objects in the module.\n\nReturns:\n An iterable of DocObject instances."
} }
} }
}, },
@@ -139,7 +139,7 @@
"kind": "class", "kind": "class",
"path": "docforge.renderers.mcp_renderer.DocObject", "path": "docforge.renderers.mcp_renderer.DocObject",
"signature": "<bound method Alias.signature of Alias('DocObject', 'docforge.models.DocObject')>", "signature": "<bound method Alias.signature of Alias('DocObject', 'docforge.models.DocObject')>",
"docstring": "Representation of a documented Python object.\n\nA `DocObject` models a single Python entity discovered during\nintrospection. Objects may contain nested members, allowing the structure\nof modules, classes, and other containers to be represented recursively.\n\nAttributes:\n name (str):\n Local name of the object.\n\n kind (str):\n Type of object (for example `class`, `function`, `method`, or `attribute`).\n\n path (str):\n Fully qualified dotted path to the object.\n\n signature (Optional[str]):\n Callable signature if the object represents a callable.\n\n docstring (Optional[str]):\n Raw docstring text extracted from the source code.\n\n members (Dict[str, DocObject]):\n Mapping of member names to child `DocObject` instances.", "docstring": "Represents a documented Python object (class, function, method, etc.).\n\nAttributes:\n name: Local name of the object.\n kind: Type of object (e.g., 'class', 'function', 'attribute').\n path: Full dotted import path to the object.\n signature: Callable signature, if applicable.\n docstring: Raw docstring content extracted from the source.\n members: Dictionary mapping member names to their DocObject representations.",
"members": { "members": {
"name": { "name": {
"name": "name", "name": "name",
@@ -188,21 +188,21 @@
"kind": "function", "kind": "function",
"path": "docforge.renderers.mcp_renderer.DocObject.add_member", "path": "docforge.renderers.mcp_renderer.DocObject.add_member",
"signature": "<bound method Alias.signature of Alias('add_member', 'docforge.models.object.DocObject.add_member')>", "signature": "<bound method Alias.signature of Alias('add_member', 'docforge.models.object.DocObject.add_member')>",
"docstring": "Add a child documentation object.\n\nThis is typically used when attaching methods to classes or\nnested objects to their parent containers.\n\nArgs:\n obj: Documentation object to add as a member." "docstring": "Add a child member to this object (e.g., a method to a class).\n\nArgs:\n obj: The child DocObject to add."
}, },
"get_member": { "get_member": {
"name": "get_member", "name": "get_member",
"kind": "function", "kind": "function",
"path": "docforge.renderers.mcp_renderer.DocObject.get_member", "path": "docforge.renderers.mcp_renderer.DocObject.get_member",
"signature": "<bound method Alias.signature of Alias('get_member', 'docforge.models.object.DocObject.get_member')>", "signature": "<bound method Alias.signature of Alias('get_member', 'docforge.models.object.DocObject.get_member')>",
"docstring": "Retrieve a member object by name.\n\nArgs:\n name (str):\n Name of the member to retrieve.\n\nReturns:\n DocObject:\n The corresponding `DocObject` instance.\n\nRaises:\n KeyError:\n If the member does not exist." "docstring": "Retrieve a child member by name.\n\nArgs:\n name: The name of the member.\n\nReturns:\n The requested DocObject."
}, },
"get_all_members": { "get_all_members": {
"name": "get_all_members", "name": "get_all_members",
"kind": "function", "kind": "function",
"path": "docforge.renderers.mcp_renderer.DocObject.get_all_members", "path": "docforge.renderers.mcp_renderer.DocObject.get_all_members",
"signature": "<bound method Alias.signature of Alias('get_all_members', 'docforge.models.object.DocObject.get_all_members')>", "signature": "<bound method Alias.signature of Alias('get_all_members', 'docforge.models.object.DocObject.get_all_members')>",
"docstring": "Return all child members of the object.\n\nReturns:\n Iterable[DocObject]:\n An iterable of `DocObject` instances representing nested members." "docstring": "Get all members of this object.\n\nReturns:\n An iterable of child DocObject instances."
} }
} }
}, },
@@ -210,8 +210,8 @@
"name": "MCPRenderer", "name": "MCPRenderer",
"kind": "class", "kind": "class",
"path": "docforge.renderers.mcp_renderer.MCPRenderer", "path": "docforge.renderers.mcp_renderer.MCPRenderer",
"signature": "<bound method Class.signature of Class('MCPRenderer', 17, 159)>", "signature": "<bound method Class.signature of Class('MCPRenderer', 8, 122)>",
"docstring": "Renderer that generates MCP-compatible documentation resources.\n\nThis renderer converts doc-forge project models into structured JSON\nresources suitable for consumption by systems implementing the Model\nContext Protocol (MCP).", "docstring": "Renderer that emits MCP-native JSON resources from docforge models.",
"members": { "members": {
"name": { "name": {
"name": "name", "name": "name",
@@ -224,8 +224,8 @@
"name": "generate_sources", "name": "generate_sources",
"kind": "function", "kind": "function",
"path": "docforge.renderers.mcp_renderer.MCPRenderer.generate_sources", "path": "docforge.renderers.mcp_renderer.MCPRenderer.generate_sources",
"signature": "<bound method Function.signature of Function('generate_sources', 28, 72)>", "signature": "<bound method Function.signature of Function('generate_sources', 15, 53)>",
"docstring": "Generate MCP documentation resources for a project.\n\nThe renderer serializes each module into a JSON resource and produces\nsupporting metadata files such as `nav.json` and `index.json`.\n\nArgs:\n project (Project):\n Documentation project model to render.\n\n out_dir (Path):\n Directory where MCP resources will be written." "docstring": "Generate MCP-compatible JSON resources and navigation for the project.\n\nArgs:\n project: The project model to render.\n out_dir: Target directory for the generated JSON files."
} }
} }
} }

80
mcp_docs/modules/docforge.renderers.mkdocs_renderer.json
View File

@@ -2,7 +2,7 @@
"module": "docforge.renderers.mkdocs_renderer", "module": "docforge.renderers.mkdocs_renderer",
"content": { "content": {
"path": "docforge.renderers.mkdocs_renderer", "path": "docforge.renderers.mkdocs_renderer",
"docstring": "# Summary\n\nMkDocs renderer implementation.\n\nThis module defines the `MkDocsRenderer` class, which generates Markdown\ndocumentation sources compatible with MkDocs Material and the mkdocstrings\nplugin.\n\nThe renderer ensures a consistent documentation structure by:\n\n- Creating a root `index.md` if one does not exist\n- Generating package index pages automatically\n- Linking child modules within parent package pages\n- Optionally generating `README.md` from the root package docstring", "docstring": "This module implements the MkDocsRenderer, which generates Markdown source files\ncompatible with the MkDocs 'material' theme and 'mkdocstrings' extension.",
"objects": { "objects": {
"Path": { "Path": {
"name": "Path", "name": "Path",
@@ -16,7 +16,7 @@
"kind": "class", "kind": "class",
"path": "docforge.renderers.mkdocs_renderer.Project", "path": "docforge.renderers.mkdocs_renderer.Project",
"signature": "<bound method Alias.signature of Alias('Project', 'docforge.models.Project')>", "signature": "<bound method Alias.signature of Alias('Project', 'docforge.models.Project')>",
"docstring": "Representation of a documentation project.\n\nA `Project` serves as the root container for all modules discovered during\nintrospection. Each module is stored by its dotted import path.\n\nAttributes:\n name (str):\n Name of the project.\n\n modules (Dict[str, Module]):\n Mapping of module paths to `Module` instances.", "docstring": "Represents a documentation project, serving as a container for modules.\n\nAttributes:\n name: Name of the project.\n modules: Dictionary mapping module paths to Module instances.",
"members": { "members": {
"name": { "name": {
"name": "name", "name": "name",
@@ -37,37 +37,67 @@
"kind": "function", "kind": "function",
"path": "docforge.renderers.mkdocs_renderer.Project.add_module", "path": "docforge.renderers.mkdocs_renderer.Project.add_module",
"signature": "<bound method Alias.signature of Alias('add_module', 'docforge.models.project.Project.add_module')>", "signature": "<bound method Alias.signature of Alias('add_module', 'docforge.models.project.Project.add_module')>",
"docstring": "Register a module in the project.\n\nArgs:\n module (Module):\n Module instance to add to the project." "docstring": "Add a module to the project.\n\nArgs:\n module: The module to add."
}, },
"get_module": { "get_module": {
"name": "get_module", "name": "get_module",
"kind": "function", "kind": "function",
"path": "docforge.renderers.mkdocs_renderer.Project.get_module", "path": "docforge.renderers.mkdocs_renderer.Project.get_module",
"signature": "<bound method Alias.signature of Alias('get_module', 'docforge.models.project.Project.get_module')>", "signature": "<bound method Alias.signature of Alias('get_module', 'docforge.models.project.Project.get_module')>",
"docstring": "Retrieve a module by its dotted path.\n\nArgs:\n path (str):\n Fully qualified dotted module path (for example `pkg.module`).\n\nReturns:\n Module:\n The corresponding `Module` instance.\n\nRaises:\n KeyError:\n If the module does not exist in the project." "docstring": "Retrieve a module by its dotted path.\n\nArgs:\n path: The dotted path of the module (e.g., 'pkg.mod').\n\nReturns:\n The requested Module."
}, },
"get_all_modules": { "get_all_modules": {
"name": "get_all_modules", "name": "get_all_modules",
"kind": "function", "kind": "function",
"path": "docforge.renderers.mkdocs_renderer.Project.get_all_modules", "path": "docforge.renderers.mkdocs_renderer.Project.get_all_modules",
"signature": "<bound method Alias.signature of Alias('get_all_modules', 'docforge.models.project.Project.get_all_modules')>", "signature": "<bound method Alias.signature of Alias('get_all_modules', 'docforge.models.project.Project.get_all_modules')>",
"docstring": "Return all modules contained in the project.\n\nReturns:\n Iterable[Module]:\n An iterable of `Module` instances." "docstring": "Get all modules in the project.\n\nReturns:\n An iterable of Module objects."
}, },
"get_module_list": { "get_module_list": {
"name": "get_module_list", "name": "get_module_list",
"kind": "function", "kind": "function",
"path": "docforge.renderers.mkdocs_renderer.Project.get_module_list", "path": "docforge.renderers.mkdocs_renderer.Project.get_module_list",
"signature": "<bound method Alias.signature of Alias('get_module_list', 'docforge.models.project.Project.get_module_list')>", "signature": "<bound method Alias.signature of Alias('get_module_list', 'docforge.models.project.Project.get_module_list')>",
"docstring": "Return the list of module import paths.\n\nReturns:\n list[str]:\n A list containing the dotted paths of all modules in the project." "docstring": "Get the list of all module dotted paths.\n\nReturns:\n A list of module paths."
} }
} }
}, },
"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": { "Module": {
"name": "Module", "name": "Module",
"kind": "class", "kind": "class",
"path": "docforge.renderers.mkdocs_renderer.Module", "path": "docforge.renderers.mkdocs_renderer.Module",
"signature": "<bound method Alias.signature of Alias('Module', 'docforge.models.Module')>", "signature": "<bound method Alias.signature of Alias('Module', 'docforge.models.Module')>",
"docstring": "Representation of a documented Python module or package.\n\nA `Module` stores metadata about the module itself and maintains a\ncollection of top-level documentation objects discovered during\nintrospection.\n\nAttributes:\n path (str):\n Dotted import path of the module.\n\n docstring (Optional[str]):\n Module-level documentation string, if present.\n\n members (Dict[str, DocObject]):\n Mapping of object names to their corresponding `DocObject` representations.", "docstring": "Represents a documented Python module or package.\n\nAttributes:\n path: Dotted import path of the module.\n docstring: Module-level docstring content.\n members: Dictionary mapping object names to their DocObject representations.",
"members": { "members": {
"path": { "path": {
"name": "path", "name": "path",
@@ -95,51 +125,21 @@
"kind": "function", "kind": "function",
"path": "docforge.renderers.mkdocs_renderer.Module.add_object", "path": "docforge.renderers.mkdocs_renderer.Module.add_object",
"signature": "<bound method Alias.signature of Alias('add_object', 'docforge.models.module.Module.add_object')>", "signature": "<bound method Alias.signature of Alias('add_object', 'docforge.models.module.Module.add_object')>",
"docstring": "Add a documented object to the module.\n\nArgs:\n obj (DocObject):\n Documentation object to register as a top-level member of the module." "docstring": "Add a documented object to the module.\n\nArgs:\n obj: The object to add."
}, },
"get_object": { "get_object": {
"name": "get_object", "name": "get_object",
"kind": "function", "kind": "function",
"path": "docforge.renderers.mkdocs_renderer.Module.get_object", "path": "docforge.renderers.mkdocs_renderer.Module.get_object",
"signature": "<bound method Alias.signature of Alias('get_object', 'docforge.models.module.Module.get_object')>", "signature": "<bound method Alias.signature of Alias('get_object', 'docforge.models.module.Module.get_object')>",
"docstring": "Retrieve a documented object by name.\n\nArgs:\n name (str):\n Name of the object to retrieve.\n\nReturns:\n DocObject:\n The corresponding `DocObject` instance.\n\nRaises:\n KeyError:\n If no object with the given name exists." "docstring": "Retrieve a member object by name.\n\nArgs:\n name: The name of the object.\n\nReturns:\n The requested DocObject."
}, },
"get_all_objects": { "get_all_objects": {
"name": "get_all_objects", "name": "get_all_objects",
"kind": "function", "kind": "function",
"path": "docforge.renderers.mkdocs_renderer.Module.get_all_objects", "path": "docforge.renderers.mkdocs_renderer.Module.get_all_objects",
"signature": "<bound method Alias.signature of Alias('get_all_objects', 'docforge.models.module.Module.get_all_objects')>", "signature": "<bound method Alias.signature of Alias('get_all_objects', 'docforge.models.module.Module.get_all_objects')>",
"docstring": "Return all top-level documentation objects in the module.\n\nReturns:\n Iterable[DocObject]:\n An iterable of `DocObject` instances representing the module's public members." "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', 22, 305)>",
"docstring": "Renderer that produces Markdown documentation for MkDocs.\n\nGenerated pages use mkdocstrings directives to reference Python modules,\nallowing MkDocs to render API documentation dynamically.",
"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', 36, 78)>",
"docstring": "Generate Markdown documentation files for a project.\n\nThis method renders a documentation structure from the provided\nproject model and writes the resulting Markdown files to the\nspecified output directory.\n\nArgs:\n project (Project):\n Project model containing modules to document.\n\n out_dir (Path):\n Directory where generated Markdown files will be written.\n\n module_is_source (bool, optional):\n If True, treat the specified module as the documentation root\n rather than nesting it inside a folder."
},
"generate_readme": {
"name": "generate_readme",
"kind": "function",
"path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_readme",
"signature": "<bound method Function.signature of Function('generate_readme', 80, 139)>",
"docstring": "Generate a `README.md` file from the root module docstring.\n\nBehavior:\n\n- If `module_is_source` is True, `README.md` is written to the project\n root directory.\n- If False, README generation is currently not implemented.\n\nArgs:\n project (Project):\n Project model containing documentation metadata.\n\n docs_dir (Path):\n Directory containing generated documentation sources.\n\n module_is_source (bool, optional):\n Whether the module is treated as the project source root."
} }
} }
} }

16
mcp_docs/modules/docforge.servers.json
View File

@@ -2,14 +2,14 @@
"module": "docforge.servers", "module": "docforge.servers",
"content": { "content": {
"path": "docforge.servers", "path": "docforge.servers",
"docstring": "# Summary\n\nServer layer for doc-forge.\n\nThis module exposes server implementations used to provide live access\nto generated documentation resources. Currently, it includes the MCP\ndocumentation server.\n\n---", "docstring": null,
"objects": { "objects": {
"MCPServer": { "MCPServer": {
"name": "MCPServer", "name": "MCPServer",
"kind": "class", "kind": "class",
"path": "docforge.servers.MCPServer", "path": "docforge.servers.MCPServer",
"signature": "<bound method Alias.signature of Alias('MCPServer', 'docforge.servers.mcp_server.MCPServer')>", "signature": "<bound method Alias.signature of Alias('MCPServer', 'docforge.servers.mcp_server.MCPServer')>",
"docstring": "MCP server for serving a pre-generated documentation bundle.\n\nThe server exposes documentation resources and diagnostic tools through\nMCP endpoints backed by JSON files generated by the MCP renderer.", "docstring": "MCP server for serving a pre-built MCP documentation bundle.",
"members": { "members": {
"mcp_root": { "mcp_root": {
"name": "mcp_root", "name": "mcp_root",
@@ -30,7 +30,7 @@
"kind": "function", "kind": "function",
"path": "docforge.servers.MCPServer.run", "path": "docforge.servers.MCPServer.run",
"signature": "<bound method Alias.signature of Alias('run', 'docforge.servers.mcp_server.MCPServer.run')>", "signature": "<bound method Alias.signature of Alias('run', 'docforge.servers.mcp_server.MCPServer.run')>",
"docstring": "Start the MCP server.\n\nArgs:\n transport (Literal[\"stdio\", \"sse\", \"streamable-http\"]):\n Transport mechanism used by the MCP server. Supported options\n include `stdio`, `sse`, and `streamable-http`." "docstring": "Start the MCP server.\n\nArgs:\n transport: MCP transport (default: streamable-http)"
} }
} }
}, },
@@ -39,7 +39,7 @@
"kind": "module", "kind": "module",
"path": "docforge.servers.mcp_server", "path": "docforge.servers.mcp_server",
"signature": null, "signature": null,
"docstring": "# Summary\n\nMCP server implementation.\n\nThis module defines the `MCPServer` class, which serves pre-generated\ndocumentation bundles through the Model Context Protocol (MCP).", "docstring": null,
"members": { "members": {
"annotations": { "annotations": {
"name": "annotations", "name": "annotations",
@@ -87,8 +87,8 @@
"name": "MCPServer", "name": "MCPServer",
"kind": "class", "kind": "class",
"path": "docforge.servers.mcp_server.MCPServer", "path": "docforge.servers.mcp_server.MCPServer",
"signature": "<bound method Class.signature of Class('MCPServer', 19, 136)>", "signature": "<bound method Class.signature of Class('MCPServer', 10, 95)>",
"docstring": "MCP server for serving a pre-generated documentation bundle.\n\nThe server exposes documentation resources and diagnostic tools through\nMCP endpoints backed by JSON files generated by the MCP renderer.", "docstring": "MCP server for serving a pre-built MCP documentation bundle.",
"members": { "members": {
"mcp_root": { "mcp_root": {
"name": "mcp_root", "name": "mcp_root",
@@ -108,8 +108,8 @@
"name": "run", "name": "run",
"kind": "function", "kind": "function",
"path": "docforge.servers.mcp_server.MCPServer.run", "path": "docforge.servers.mcp_server.MCPServer.run",
"signature": "<bound method Function.signature of Function('run', 124, 136)>", "signature": "<bound method Function.signature of Function('run', 88, 95)>",
"docstring": "Start the MCP server.\n\nArgs:\n transport (Literal[\"stdio\", \"sse\", \"streamable-http\"]):\n Transport mechanism used by the MCP server. Supported options\n include `stdio`, `sse`, and `streamable-http`." "docstring": "Start the MCP server.\n\nArgs:\n transport: MCP transport (default: streamable-http)"
} }
} }
} }

10
mcp_docs/modules/docforge.servers.mcp_server.json
View File

@@ -2,7 +2,7 @@
"module": "docforge.servers.mcp_server", "module": "docforge.servers.mcp_server",
"content": { "content": {
"path": "docforge.servers.mcp_server", "path": "docforge.servers.mcp_server",
"docstring": "# Summary\n\nMCP server implementation.\n\nThis module defines the `MCPServer` class, which serves pre-generated\ndocumentation bundles through the Model Context Protocol (MCP).", "docstring": null,
"objects": { "objects": {
"annotations": { "annotations": {
"name": "annotations", "name": "annotations",
@@ -50,8 +50,8 @@
"name": "MCPServer", "name": "MCPServer",
"kind": "class", "kind": "class",
"path": "docforge.servers.mcp_server.MCPServer", "path": "docforge.servers.mcp_server.MCPServer",
"signature": "<bound method Class.signature of Class('MCPServer', 19, 136)>", "signature": "<bound method Class.signature of Class('MCPServer', 10, 95)>",
"docstring": "MCP server for serving a pre-generated documentation bundle.\n\nThe server exposes documentation resources and diagnostic tools through\nMCP endpoints backed by JSON files generated by the MCP renderer.", "docstring": "MCP server for serving a pre-built MCP documentation bundle.",
"members": { "members": {
"mcp_root": { "mcp_root": {
"name": "mcp_root", "name": "mcp_root",
@@ -71,8 +71,8 @@
"name": "run", "name": "run",
"kind": "function", "kind": "function",
"path": "docforge.servers.mcp_server.MCPServer.run", "path": "docforge.servers.mcp_server.MCPServer.run",
"signature": "<bound method Function.signature of Function('run', 124, 136)>", "signature": "<bound method Function.signature of Function('run', 88, 95)>",
"docstring": "Start the MCP server.\n\nArgs:\n transport (Literal[\"stdio\", \"sse\", \"streamable-http\"]):\n Transport mechanism used by the MCP server. Supported options\n include `stdio`, `sse`, and `streamable-http`." "docstring": "Start the MCP server.\n\nArgs:\n transport: MCP transport (default: streamable-http)"
} }
} }
} }

77
mkdocs.yml
View File

@@ -1,3 +1,5 @@
site_name: docforge
theme: theme:
name: material name: material
palette: palette:
@@ -8,19 +10,12 @@ theme:
text: Inter text: Inter
code: JetBrains Mono code: JetBrains Mono
features: features:
- navigation.sections - navigation.tabs
- navigation.expand - navigation.expand
- navigation.top - navigation.top
- navigation.instant - navigation.instant
- navigation.tracking
- navigation.indexes
- content.code.copy - content.code.copy
- content.code.annotate - content.code.annotate
- content.tabs.link
- content.action.edit
- search.highlight
- search.share
- search.suggest
plugins: plugins:
- search - search
- mkdocstrings: - mkdocstrings:
@@ -38,54 +33,30 @@ plugins:
annotations_path: brief annotations_path: brief
show_root_heading: true show_root_heading: true
group_by_category: true group_by_category: true
show_category_heading: true
show_object_full_path: false
show_symbol_type_heading: true
markdown_extensions:
- pymdownx.superfences
- pymdownx.inlinehilite
- pymdownx.snippets
- admonition
- pymdownx.details
- pymdownx.superfences
- pymdownx.highlight:
linenums: true
anchor_linenums: true
line_spans: __span
pygments_lang_class: true
- pymdownx.tabbed:
alternate_style: true
- pymdownx.tasklist:
custom_checkbox: true
- tables
- footnotes
- pymdownx.caret
- pymdownx.tilde
- pymdownx.mark
site_name: docforge
nav: nav:
- Home: index.md - Home: docforge/index.md
- Loaders: - Loaders:
- loaders/index.md - docforge/loaders/index.md
- loaders/griffe_loader.md - docforge/loaders/griffe_loader.md
- Models: - Models:
- models/index.md - docforge/models/index.md
- models/module.md - docforge/models/module.md
- models/object.md - docforge/models/object.md
- models/project.md - docforge/models/project.md
- Navigation: - Navigation:
- nav/index.md - docforge/nav/index.md
- nav/spec.md - docforge/nav/spec.md
- nav/resolver.md - docforge/nav/resolver.md
- nav/mkdocs.md - docforge/nav/mkdocs.md
- Renderers: - Renderers:
- renderers/index.md - docforge/renderers/index.md
- renderers/base.md - docforge/renderers/base.md
- renderers/mkdocs_renderer.md - docforge/renderers/mkdocs_renderer.md
- renderers/mcp_renderer.md - docforge/renderers/mcp_renderer.md
- CLI: - CLI:
- cli/index.md - docforge/cli/index.md
- cli/main.md - docforge/cli/main.md
- cli/commands.md - docforge/cli/commands.md
- cli/mcp_utils.md - docforge/cli/mcp_utils.md
- cli/mkdocs_utils.md - docforge/cli/mkdocs_utils.md

2
pyproject.toml
View File

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

2
tests/cli/test_serve_mcp.py
View File

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

31
tests/renderers/mkdocs/test_mkdocs_content.py
View File

@@ -17,34 +17,3 @@ def test_mkdocs_file_content(tmp_path: Path):
assert "# Mod" in content assert "# Mod" in content
assert "::: testpkg.mod" in content assert "::: testpkg.mod" in content
def test_generate_readme_source_root(tmp_path: Path):
project = Project("testpkg")
root = Module("testpkg")
root.docstring = "Test package documentation."
project.add_module(root)
project.add_module(Module("testpkg.mod"))
docs_dir = tmp_path / "docs"
renderer = MkDocsRenderer()
renderer.generate_sources(project, docs_dir)
renderer.generate_readme(
project,
docs_dir,
module_is_source=True,
)
readme = tmp_path / "README.md"
assert readme.exists()
content = readme.read_text()
assert "# testpkg" in content
assert "Test package documentation." in content

33
tests/renderers/mkdocs/test_mkdocs_idempotency.py
View File

@@ -18,36 +18,3 @@ def test_mkdocs_idempotent(tmp_path: Path):
second = (out_dir / "testpkg" / "mod.md").read_text() second = (out_dir / "testpkg" / "mod.md").read_text()
assert first == second assert first == second
def test_generate_readme_idempotent(tmp_path: Path):
project = Project("testpkg")
root = Module("testpkg")
root.docstring = "Test package documentation."
project.add_module(root)
docs_dir = tmp_path / "docs"
renderer = MkDocsRenderer()
renderer.generate_readme(
project,
docs_dir,
module_is_source=True,
)
readme = tmp_path / "README.md"
first = readme.read_text()
renderer.generate_readme(
project,
docs_dir,
module_is_source=True,
)
second = readme.read_text()
assert first == second

11
tests/renderers/mkdocs/test_mkdocs_module_coverage.py
View File

@@ -17,12 +17,6 @@ def test_mkdocs_emits_all_modules(tmp_path: Path) -> None:
renderer = MkDocsRenderer() renderer = MkDocsRenderer()
renderer.generate_sources(project, tmp_path) renderer.generate_sources(project, tmp_path)
renderer.generate_readme(
project,
tmp_path,
module_is_source=True,
)
emitted = { emitted = {
p.relative_to(tmp_path).as_posix() p.relative_to(tmp_path).as_posix()
for p in tmp_path.rglob("*.md") for p in tmp_path.rglob("*.md")
@@ -45,8 +39,3 @@ def test_mkdocs_emits_all_modules(tmp_path: Path) -> None:
missing = expected - emitted missing = expected - emitted
assert not missing, f"Missing markdown files for modules: {missing}" assert not missing, f"Missing markdown files for modules: {missing}"
readme = tmp_path.parent / "README.md"
assert readme.exists(), "README.md was not generated"
content = readme.read_text(encoding="utf-8")
assert project.name in content

6
tests/renderers/mkdocs/test_mkdocs_structure.py
View File

@@ -13,12 +13,6 @@ def test_mkdocs_directory_structure(tmp_path: Path):
renderer = MkDocsRenderer() renderer = MkDocsRenderer()
renderer.generate_sources(project, out_dir) renderer.generate_sources(project, out_dir)
renderer.generate_readme(
project,
out_dir,
module_is_source=True,
)
assert (out_dir / "testpkg" / "index.md").exists() assert (out_dir / "testpkg" / "index.md").exists()
assert (out_dir / "testpkg" / "sub.md").exists() assert (out_dir / "testpkg" / "sub.md").exists()
assert (tmp_path / "README.md").exists()