From b6306baafc7e91cc5335b95c790fe25825b6fc05 Mon Sep 17 00:00:00 2001 From: Vishesh 'ironeagle' Bangotra Date: Sat, 7 Mar 2026 10:50:18 +0000 Subject: [PATCH] Improve documentation look & feel via MkDocs Material template enhancements (#5) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit # Improve documentation look & feel via MkDocs Material template enhancements ## Summary This MR improves the overall **documentation experience and visual presentation** of the doc-forge docs by enhancing the MkDocs Material template configuration. The changes focus on **navigation usability, code readability, and richer Markdown rendering**, resulting in a cleaner and more professional documentation site. Docstring changes were made across the codebase for consistency, but this MR description focuses on the **template and presentation improvements**. --- ## Navigation Improvements The navigation system has been enhanced to provide a clearer structure and better discoverability. Key improvements include: * Section-aware navigation in the sidebar * Automatic expansion of module/package hierarchy * Scroll tracking within the sidebar * Clickable package index pages Material navigation features added: * `navigation.sections` * `navigation.expand` * `navigation.tracking` * `navigation.indexes` This results in a **single cohesive navigation tree** that exposes the entire documentation hierarchy from the sidebar. --- ## Code Block Improvements Code blocks previously appeared relatively plain. The template now enables richer syntax highlighting and improved readability. Enhancements include: * Syntax highlighting using `pymdownx.highlight` * Line numbers for code blocks * Anchored line numbers for deep linking * Improved fenced code block rendering Additional Material features: * `content.code.copy` — copy button for code blocks * `content.code.annotate` — support for code annotations These changes significantly improve the readability of examples and API snippets throughout the documentation. --- ## Markdown Rendering Enhancements Additional Markdown extensions were enabled to support richer documentation features: * `pymdownx.superfences` for advanced fenced blocks * `pymdownx.inlinehilite` for inline code highlighting * `pymdownx.snippets` for reusable snippets * `admonition` and `pymdownx.details` for callouts and collapsible sections * `pymdownx.tabbed` for tabbed content blocks * `pymdownx.tasklist` for checklist-style items * `tables`, `footnotes`, and advanced formatting extensions These extensions make it easier to write expressive and structured documentation. --- ## Search Experience The documentation search experience has been improved using Material search features: * `search.highlight` * `search.share` * `search.suggest` These enhancements provide: * highlighted search matches * sharable search URLs * auto-suggestions while typing --- ## mkdocstrings Improvements The mkdocstrings configuration has been expanded to produce clearer API documentation. Notable improvements include: * grouping objects by category * explicit category headings * improved symbol headings * cleaner object path display This results in more structured API documentation pages. --- ## Result Overall, these changes provide: * cleaner and more intuitive navigation * significantly improved code presentation * richer Markdown capabilities * better search usability The documentation now has a **more polished, modern appearance** and improved usability for both readers and contributors. Reviewed-on: https://git.aetoskia.com/aetos/doc-forge/pulls/5 Co-authored-by: Vishesh 'ironeagle' Bangotra Co-committed-by: Vishesh 'ironeagle' Bangotra --- README.md | 768 ++++++++++++------ docforge/cli/__init__.py | 31 +- docforge/cli/commands.py | 88 +- docforge/cli/main.py | 17 +- docforge/cli/mcp_utils.py | 32 +- docforge/cli/mkdocs_utils.py | 75 +- docforge/loaders/__init__.py | 30 +- docforge/loaders/griffe_loader.py | 112 ++- docforge/models/__init__.py | 33 +- docforge/models/module.py | 43 +- docforge/models/object.py | 66 +- docforge/models/project.py | 39 +- docforge/nav/__init__.py | 27 +- docforge/nav/mkdocs.py | 39 +- docforge/nav/resolver.py | 60 +- docforge/nav/spec.py | 57 +- docforge/renderers/__init__.py | 36 +- docforge/renderers/base.py | 34 +- docforge/renderers/mcp_renderer.py | 42 +- docforge/renderers/mkdocs_renderer.py | 164 +++- docforge/renderers/mkdocs_renderer.pyi | 7 + docforge/servers/__init__.py | 12 +- docforge/servers/mcp_server.py | 51 +- docforge/templates/mkdocs.sample.yml | 42 +- mcp_docs/modules/docforge.cli.commands.json | 73 +- mcp_docs/modules/docforge.cli.json | 148 ++-- mcp_docs/modules/docforge.cli.main.json | 6 +- mcp_docs/modules/docforge.cli.mcp_utils.json | 24 +- .../modules/docforge.cli.mkdocs_utils.json | 43 +- mcp_docs/modules/docforge.json | 529 ++++++------ .../docforge.loaders.griffe_loader.json | 44 +- mcp_docs/modules/docforge.loaders.json | 54 +- mcp_docs/modules/docforge.models.json | 102 +-- mcp_docs/modules/docforge.models.module.json | 26 +- mcp_docs/modules/docforge.models.object.json | 18 +- mcp_docs/modules/docforge.models.project.json | 30 +- mcp_docs/modules/docforge.nav.json | 72 +- mcp_docs/modules/docforge.nav.mkdocs.json | 14 +- mcp_docs/modules/docforge.nav.resolver.json | 20 +- mcp_docs/modules/docforge.nav.spec.json | 18 +- mcp_docs/modules/docforge.renderers.base.json | 24 +- mcp_docs/modules/docforge.renderers.json | 110 +-- .../docforge.renderers.mcp_renderer.json | 34 +- .../docforge.renderers.mkdocs_renderer.json | 35 +- mcp_docs/modules/docforge.servers.json | 14 +- .../modules/docforge.servers.mcp_server.json | 8 +- mkdocs.yml | 29 +- tests/renderers/mkdocs/test_mkdocs_content.py | 31 + .../mkdocs/test_mkdocs_idempotency.py | 33 + .../mkdocs/test_mkdocs_module_coverage.py | 11 + .../renderers/mkdocs/test_mkdocs_structure.py | 6 + 51 files changed, 2222 insertions(+), 1239 deletions(-) diff --git a/README.md b/README.md index 8d437bc..8fccfd1 100644 --- a/README.md +++ b/README.md @@ -1,244 +1,534 @@ -# doc-forge +# docforge -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 +into structured documentation for both humans (MkDocs) and machines (MCP / AI agents). -## Features - -- **Single Source of Truth**: Python source code and docstrings are the only authoritative input -- **Renderer Agnosticism**: MkDocs, Sphinx, MCP, or future renderers don't influence the core model -- **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 - -```bash -pip install doc-forge -``` - -### Optional Dependencies - -```bash -# 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] -``` - -## Quick Start - -### Command Line Interface - -```bash -# 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 - -```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 -doc-forge generate --renderer mkdocs --out-dir docs mypackage -``` - -### `build` -Build final documentation artifacts (HTML, etc.). - -```bash -doc-forge build --renderer sphinx mypackage -``` - -### `serve` -Start a local development server. - -```bash -doc-forge serve --renderer mkdocs --port 9000 mypackage -``` - -### `export` -Export to MCP format for machine consumption. - -```bash -doc-forge export --out-dir mcp mypackage -``` - -### `server` -Start live MCP server for real-time access. - -```bash -doc-forge server --host 0.0.0.0 --port 8080 mypackage -``` - -## 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 +`doc-forge` statically analyzes source code, builds a semantic model of modules, +classes, functions, and attributes, and renders that model into documentation +outputs without executing user code. --- -*doc-forge turns Python code into structured knowledge and emits it through multiple human and machine interfaces.* \ No newline at end of file +## Installation + +Install using pip: + + pip install doc-forge + +--- + +## Quick start + +Generate a MkDocs site from a Python package: + + doc-forge build --mkdocs --module my_package + +Generate MCP JSON documentation: + + doc-forge build --mcp --module my_package + +Serve documentation locally: + + doc-forge serve --mkdocs --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 + +--- + +## CLI usage + +Build MkDocs documentation: + + doc-forge build --mkdocs --module my_package + +Build MCP documentation: + + doc-forge build --mcp --module my_package + +Serve MkDocs locally: + + doc-forge serve --module my_package + +--- + +## Public API + +Loaders: + + GriffeLoader + discover_module_paths + +Renderers: + + MkDocsRenderer + MCPRenderer + +CLI: + + main + +Models: + + models + +--- + +# 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. +- Indent section contents using four spaces. +- Use type hints in signatures instead of duplicating types in prose. +- Write summaries in imperative form. +- Sections are separated by ```---``` + +--- + +## Package docstrings + +- Package docstrings act as the documentation home page. + +Recommended sections: + + ## Summary + ## Installation + ## Quick start + ## Core concepts + ## Architecture + ## Rendering pipeline + ## CLI usage + ## Public API + ## Examples + ## Notes + +Example: + Package Doc String: + + ''' + Foo-bar processing framework. + + Provides tools for defining Foo objects and executing Bar pipelines. + + --- + + # Installation + + pip install foo-bar + + --- + + # Quick start + + from foobar import Foo, BarEngine + + foo = Foo("example") + engine = BarEngine([foo]) + + result = engine.run() + + --- + + # Public API + + Foo + Bar + BarEngine + + --- + ''' + +--- + +## Module docstrings + +- Module docstrings describe a subsystem. + +Recommended sections: + + ## Summary + ## Examples + ## Notes + ## Public API + +Example: + Module Doc String: + + ''' + Foo execution subsystem. + + Provides utilities for executing Foo objects through Bar stages. + + --- + + Example: + + 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: + + 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: + + foo = Foo("example", value=42) + print(foo.name) + ''' + + Complex Bar: + + 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: + + 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: + + 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: + + foo = Foo("example", value=10) + + result = process(foo, multiplier=2) + print(result) + ''' + + Multiple Examples: + + 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: + + foo1 = Foo("a") + foo2 = Foo("b") + + combined = combine(foo1, foo2) + + Pipeline usage: + + engine = BarEngine([foo1, foo2]) + engine.run() + ''' + +--- + +## Property docstrings + +- Properties must document return values. + +Example: + Property Doc String: + + @property + def foos(self) -> tuple[Foo, ...]: + ''' + Return contained Foo instances. + + Returns: + tuple[Foo, ...]: + Stored foo objects. + + Example: + container = FooContainer() + + foos = container.foos + ''' + +--- + +## Attribute documentation + +- Document attributes in class docstrings using Attributes:. + +Example: + Attribute Doc String: + + ''' + Represents a processing stage. + + Attributes: + id (str): + Unique identifier. + + enabled (bool): + Whether the stage is active. + ''' + +--- + +## Notes subsection grouping + +- Group related information using labeled subsections. + +Example: + Notes Example: + + Notes: + **Guarantees:** + + - deterministic behavior + + **Lifecycle:** + + - created during initialization + - reused across executions + + **Thread safety:** + + - safe for concurrent reads + +--- + +## Example formatting + +- Use indentation for examples. + +Example: + Single example: + + Example: + + foo = Foo("example") + process(foo, multiplier=2) + + Multiple examples: + + Example: + Create foo: + + foo = Foo("example") + + Run engine: + + 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: + + --- + +Allowed locations: + +- package docstrings +- module docstrings +- major documentation sections + +Do not use separators inside code sections. + +--- + +## 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. diff --git a/docforge/cli/__init__.py b/docforge/cli/__init__.py index 094887b..8cfe42c 100644 --- a/docforge/cli/__init__.py +++ b/docforge/cli/__init__.py @@ -1,14 +1,31 @@ """ -# 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 +``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. -## Available Commands +The CLI is responsible for orchestrating documentation workflows such as +generating renderer sources, building documentation sites, exporting +machine-readable documentation bundles, and starting development or MCP +servers. -- **build**: Build documentation (MkDocs site or MCP resources). -- **serve**: Serve documentation (MkDocs or MCP). -- **tree**: Visualize the introspected project structure. +--- + +Typical usage +------------- + +The CLI is normally invoked through the installed command: + + doc-forge [options] + +Programmatic invocation is also possible: + + from docforge.cli import main + main() + +--- """ from .main import main diff --git a/docforge/cli/commands.py b/docforge/cli/commands.py index 12305a4..2bc057b 100644 --- a/docforge/cli/commands.py +++ b/docforge/cli/commands.py @@ -9,8 +9,10 @@ from docforge.cli import mcp_utils @click.group() def cli() -> None: """ - doc-forge CLI: A tool for introspecting Python projects and generating - documentation. + Root command group for the doc-forge CLI. + + Provides commands for building, serving, and inspecting + documentation generated from Python source code. """ pass @@ -21,14 +23,12 @@ def cli() -> None: @click.option("--module-is-source", is_flag=True, help="Module is source folder and to be treated as root folder") @click.option("--module", help="Python module to document") @click.option("--project-name", help="Project name override") -# MkDocs specific @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("--nav", "nav_file", type=click.Path(path_type=Path), default=Path("docforge.nav.yml"), help="Nav spec 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") -# MCP specific @click.option("--out-dir", type=click.Path(path_type=Path), default=Path("mcp_docs"), help="MCP output directory") def build( mcp: bool, @@ -44,25 +44,36 @@ def build( out_dir: Path, ) -> None: """ - Build documentation (MkDocs site or MCP resources). + Build documentation artifacts. - This command orchestrates the full build process: - 1. Introspects the code (Griffe) - 2. Renders sources (MkDocs Markdown or MCP JSON) - 3. (MkDocs only) Generates config and runs the final site build. + This command performs the full documentation build pipeline: + + 1. Introspects the Python project using Griffe + 2. Generates renderer-specific documentation sources + 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: - mcp: Use the MCP documentation builder. - mkdocs: Use the MkDocs documentation builder. - module_is_source: Module is the source folder and to be treated as the root folder. - module: The dotted path of the module to the document. + mcp: Enable MCP documentation generation. + mkdocs: Enable MkDocs documentation generation. + module_is_source: Treat the specified module directory as the + project root. + module: Python module import path to document. project_name: Optional override for the project name. - site_name: (MkDocs) The site display name. Defaults to module name. - docs_dir: (MkDocs) Target directory for Markdown sources. - nav_file: (MkDocs) Path to the docforge.nav.yml specification. - template: (MkDocs) Optional custom mkdocs.yml template. - mkdocs_yml: (MkDocs) Target path for the generated mkdocs.yml. - out_dir: (MCP) Target directory for MCP JSON resources. + site_name: Display name for the MkDocs site. + docs_dir: Directory where Markdown documentation sources + will be generated. + nav_file: Path to the navigation specification file. + template: Optional custom MkDocs configuration template. + mkdocs_yml: Output path for the generated MkDocs configuration. + out_dir: Output directory for generated MCP resources. + + Raises: + click.UsageError: If required options are missing or conflicting. """ if not mcp and not mkdocs: raise click.UsageError("Must specify either --mcp or --mkdocs") @@ -111,14 +122,22 @@ def serve( out_dir: Path, ) -> None: """ - Serve documentation (MkDocs or MCP). + Serve generated documentation locally. + + Depending on the selected mode, this command starts either: + + - A MkDocs development server for browsing documentation + - An MCP server exposing structured documentation resources Args: - mcp: Serve MCP resources via an MCP server. - mkdocs: Serve the MkDocs site using the built-in development server. - module: The dotted path of the module to serve. - mkdocs_yml: (MkDocs) Path to the mkdocs.yml configuration. - out_dir: (MCP) Path to the mcp_docs/ directory. + mcp: Serve documentation using the MCP server. + mkdocs: Serve the MkDocs development site. + module: Python module import path to serve via MCP. + mkdocs_yml: Path to the MkDocs configuration file. + out_dir: Root directory containing MCP documentation resources. + + Raises: + click.UsageError: If invalid or conflicting options are provided. """ if mcp and mkdocs: raise click.UsageError("Cannot specify both --mcp and --mkdocs") @@ -148,11 +167,15 @@ def tree( project_name: Optional[str], ) -> None: """ - Visualize the project structure in the terminal. + Display the documentation object tree for a module. + + This command introspects the specified module and prints a + hierarchical representation of the discovered documentation + objects, including modules, classes, functions, and members. Args: - module: The module import path to recursively introspect. - project_name: Optional override for the project name shown at the root. + module: Python module import path to introspect. + project_name: Optional name to display as the project root. """ loader = GriffeLoader() project = loader.load_project([module], project_name) @@ -167,11 +190,14 @@ def tree( def _print_object(obj, indent: str) -> None: """ - Recursive helper to print doc objects and their members to the console. + Recursively print a documentation object and its members. + + This helper function traverses the documentation object graph + and prints each object with indentation to represent hierarchy. Args: - obj: The DocObject instance to print. - indent: Current line indentation (e.g., '│ '). + obj: Documentation object to print. + indent: Current indentation prefix used for nested members. """ click.echo(f"{indent}├── {obj.name}") for member in obj.get_all_members(): diff --git a/docforge/cli/main.py b/docforge/cli/main.py index 70c7051..c3b5a05 100644 --- a/docforge/cli/main.py +++ b/docforge/cli/main.py @@ -1,14 +1,23 @@ """ -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 + def main() -> None: """ - CLI Entry point. Boots the click application. + Run the doc-forge command-line interface. + + 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() + if __name__ == "__main__": - main() + main() \ No newline at end of file diff --git a/docforge/cli/mcp_utils.py b/docforge/cli/mcp_utils.py index add7dcb..f2ab54d 100644 --- a/docforge/cli/mcp_utils.py +++ b/docforge/cli/mcp_utils.py @@ -4,14 +4,22 @@ from docforge.loaders import GriffeLoader, discover_module_paths from docforge.renderers import MCPRenderer from docforge.servers import MCPServer + def generate_resources(module: str, project_name: str | None, out_dir: Path) -> None: """ - Generate MCP-compatible documentation resources. + Generate MCP documentation resources from a Python module. + + The function performs project introspection, builds the internal + documentation model, and renders MCP-compatible JSON resources + to the specified output directory. Args: - module: The dotted path of the primary module to document. - project_name: Optional override for the project name. - out_dir: Directory where the MCP JSON resources and nav will be written. + module: Python module import path used as the entry point for + documentation generation. + project_name: Optional override for the project name used in + generated documentation metadata. + out_dir: Directory where MCP resources (index.json, nav.json, + and module data) will be written. """ loader = GriffeLoader() discovered_paths = discover_module_paths(module) @@ -20,13 +28,23 @@ def generate_resources(module: str, project_name: str | None, out_dir: Path) -> renderer = MCPRenderer() renderer.generate_sources(project, out_dir) + def serve(module: str, mcp_root: Path) -> None: """ - Serve MCP documentation from a pre-built bundle. + Start an MCP server for a pre-generated documentation bundle. + + The server exposes documentation resources such as project metadata, + navigation structure, and module documentation through MCP endpoints. Args: - module: The dotted path of the primary module to serve. - mcp_root: Path to the directory containing index.json, nav.json, and modules/. + module: Python module import path used to identify the served + documentation instance. + mcp_root: 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(): raise click.ClickException(f"mcp_docs directory not found: {mcp_root}") diff --git a/docforge/cli/mkdocs_utils.py b/docforge/cli/mkdocs_utils.py index 1c135bd..01d2b11 100644 --- a/docforge/cli/mkdocs_utils.py +++ b/docforge/cli/mkdocs_utils.py @@ -6,6 +6,7 @@ from docforge.loaders import GriffeLoader, discover_module_paths from docforge.renderers import MkDocsRenderer from docforge.nav import load_nav_spec, resolve_nav, MkDocsNavEmitter + def generate_sources( module: str, docs_dir: Path, @@ -13,13 +14,20 @@ def generate_sources( module_is_source: bool | None = None, ) -> None: """ - Generate Markdown source files for the specified module. + Generate MkDocs Markdown sources for a Python module. + + This function introspects the specified module, builds the internal + documentation model, and renders Markdown documentation files for + use with MkDocs. Args: - module: The dotted path of the primary module to document. - project_name: Optional override for the project name. + module: Python module import path used as the entry point for + documentation generation. docs_dir: Directory where the generated Markdown files will be written. - module_is_source: Module is the source folder and to be treated as the root folder. + project_name: Optional override for the project name used in + documentation metadata. + module_is_source: If True, treat the specified module directory as + the project root rather than a nested module. """ loader = GriffeLoader() discovered_paths = discover_module_paths(module) @@ -32,16 +40,39 @@ def generate_sources( module_is_source, ) -def generate_config(docs_dir: Path, nav_file: Path, template: Path | None, out: Path, site_name: str) -> None: + renderer.generate_readme( + 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: - docs_dir: Path to the directory containing documentation Markdown files. - nav_file: Path to the docforge.nav.yml specification. - template: Optional path to an mkdocs.yml template (overrides built-in). - out: Path where the final mkdocs.yml will be written. - site_name: The display name for the documentation site. + docs_dir: Directory containing generated documentation Markdown files. + nav_file: Path to the ``docforge.nav.yml`` navigation specification. + template: Optional path to a custom MkDocs configuration template. + If not provided, a built-in template will be used. + out: Destination path where the generated ``mkdocs.yml`` file + will be written. + site_name: 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(): raise click.FileError(str(nav_file), hint="Nav spec not found") @@ -68,12 +99,19 @@ def generate_config(docs_dir: Path, nav_file: Path, template: Path | None, out: out.write_text(yaml.safe_dump(data, sort_keys=False), encoding="utf-8") + def build(mkdocs_yml: Path) -> None: """ - Build the documentation site using MkDocs. + Build the MkDocs documentation site. + + This function loads the MkDocs configuration and runs the MkDocs + build command to generate the final static documentation site. Args: - mkdocs_yml: Path to the mkdocs.yml configuration file. + mkdocs_yml: Path to the ``mkdocs.yml`` configuration file. + + Raises: + click.ClickException: If the configuration file does not exist. """ if not mkdocs_yml.exists(): raise click.ClickException(f"mkdocs.yml not found: {mkdocs_yml}") @@ -83,12 +121,19 @@ def build(mkdocs_yml: Path) -> None: mkdocs_build(load_config(str(mkdocs_yml))) + def serve(mkdocs_yml: Path) -> None: """ - Serve the documentation site with live-reload using MkDocs. + Start an MkDocs development server with live reload. + + The server watches documentation files and automatically reloads + the site when changes are detected. Args: - mkdocs_yml: Path to the mkdocs.yml configuration file. + mkdocs_yml: Path to the ``mkdocs.yml`` configuration file. + + Raises: + click.ClickException: If the configuration file does not exist. """ if not mkdocs_yml.exists(): raise click.ClickException(f"mkdocs.yml not found: {mkdocs_yml}") diff --git a/docforge/loaders/__init__.py b/docforge/loaders/__init__.py index 2845f8c..04f5a32 100644 --- a/docforge/loaders/__init__.py +++ b/docforge/loaders/__init__.py @@ -1,17 +1,27 @@ """ -# 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 +and extracting documentation data using static analysis. -## Core Features +--- -- **Discovery**: Automatically find all modules and packages in a project - directory. -- **Introspection**: Uses `griffe` to parse docstrings, signatures, and - hierarchical relationships without executing the code. -- **Filtering**: Automatically excludes private members (prefixed with `_`) to - ensure clean public documentation. +Overview +-------- + +This layer converts Python source code into an intermediate documentation +model used by doc-forge. It performs module discovery, introspection, and +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 diff --git a/docforge/loaders/griffe_loader.py b/docforge/loaders/griffe_loader.py index c4ff540..4505e96 100644 --- a/docforge/loaders/griffe_loader.py +++ b/docforge/loaders/griffe_loader.py @@ -1,6 +1,9 @@ """ -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 @@ -25,19 +28,27 @@ def discover_module_paths( project_root: Path | None = None, ) -> List[str]: """ - Discover all Python modules under a package via filesystem traversal. + Discover Python modules within a package directory. - Rules: - - Directory with __init__.py is treated as a package. - - Any .py file is treated as a module. - - All paths are converted to dotted module paths. + The function scans the filesystem for ``.py`` files inside the specified + package and converts them into dotted module import paths. + + Discovery rules: + + - Directories containing ``__init__.py`` are treated as packages. + - Each ``.py`` file is treated as a module. + - Results are returned as dotted import paths. Args: - module_name: The name of the package to discover. - project_root: The root directory of the project. Defaults to current working directory. + module_name: Top-level package name to discover modules from. + project_root: Root directory used to resolve module paths. If not + provided, the current working directory is used. Returns: - 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: @@ -64,12 +75,19 @@ def discover_module_paths( class GriffeLoader: """ - Loads Python modules and extracts documentation using the Griffe introspection engine. + Load Python modules using Griffe and convert them into doc-forge models. + + 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: """ - Initialize the GriffeLoader. + Initialize the Griffe-backed loader. + + Creates an internal Griffe loader instance with dedicated collections + for modules and source lines. """ self._loader = _GriffeLoader( modules_collection=ModulesCollection(), @@ -77,21 +95,32 @@ class GriffeLoader: ) def load_project( - self, - module_paths: List[str], - project_name: Optional[str] = None, - skip_import_errors: bool = None, + self, + module_paths: List[str], + project_name: Optional[str] = None, + skip_import_errors: bool = None, ) -> Project: """ - Load multiple modules and combine them into a single Project models. + Load multiple modules and assemble them into a Project model. + + Each module path is introspected and converted into a ``Module`` + instance. All modules are then aggregated into a single ``Project`` + object. Args: - module_paths: A list of dotted paths to the modules 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. + module_paths: List of dotted module import paths to load. + project_name: Optional override for the project name. Defaults + to the top-level name of the first module. + skip_import_errors: If True, modules that fail to load will be + skipped instead of raising an error. Returns: - 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: raise ValueError("At least one module path must be provided") @@ -116,13 +145,16 @@ class GriffeLoader: def load_module(self, path: str) -> Module: """ - Load a single module and convert its introspection data into the docforge models. + Load and convert a single Python module. + + The module is introspected using Griffe and then transformed into + a doc-forge ``Module`` model. Args: - path: The dotted path of the module to load. + path: Dotted import path of the module. Returns: - A Module instance. + A populated ``Module`` instance. """ self._loader.load(path) griffe_module = self._loader.modules_collection[path] @@ -135,13 +167,16 @@ class GriffeLoader: def _convert_module(self, obj: Object) -> Module: """ - Convert a Griffe Object (module) into a docforge Module. + Convert a Griffe module object into a doc-forge Module. + + All public members of the module are recursively converted into + ``DocObject`` instances. Args: - obj: The Griffe Object representing the module. + obj: Griffe object representing the module. Returns: - A populated Module instance. + A populated ``Module`` model. """ module = Module( path=obj.path, @@ -158,13 +193,17 @@ class GriffeLoader: def _convert_object(self, obj: Object) -> DocObject: """ - Recursively convert a Griffe Object into a DocObject hierarchy. + Convert a Griffe object into a doc-forge DocObject. + + The conversion preserves the object's metadata such as name, + kind, path, signature, and docstring. Child members are processed + recursively. Args: - obj: The Griffe Object to convert. + obj: Griffe object representing a documented Python object. Returns: - A DocObject instance. + A ``DocObject`` instance representing the converted object. """ kind = obj.kind.value signature = self._safe_signature(obj) @@ -193,13 +232,13 @@ class GriffeLoader: def _safe_docstring(self, obj: Object) -> Optional[str]: """ - Safely retrieve the docstring value from a Griffe object. + Safely extract a docstring from a Griffe object. Args: - obj: The Griffe Object to inspect. + obj: Griffe object to inspect. Returns: - The raw docstring string, or None if missing or unresolvable. + The raw docstring text if available, otherwise ``None``. """ try: return obj.docstring.value if obj.docstring else None @@ -208,13 +247,14 @@ class GriffeLoader: def _safe_signature(self, obj: Object) -> Optional[str]: """ - Safely retrieve the signature string from a Griffe object. + Safely extract the signature of a Griffe object. Args: - obj: The Griffe Object to inspect. + obj: Griffe object to inspect. Returns: - The string representation of the signature, or None. + String representation of the object's signature if available, + otherwise ``None``. """ try: if hasattr(obj, "signature") and obj.signature: diff --git a/docforge/models/__init__.py b/docforge/models/__init__.py index 58e0d58..8562acc 100644 --- a/docforge/models/__init__.py +++ b/docforge/models/__init__.py @@ -1,17 +1,32 @@ """ -# 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 +represent Python source code as a structured documentation model. -## Key Components +--- -- **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 diff --git a/docforge/models/module.py b/docforge/models/module.py index 498bfc9..ecd762b 100644 --- a/docforge/models/module.py +++ b/docforge/models/module.py @@ -1,7 +1,10 @@ """ -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 -documented objects. +Documentation model representing a Python module or package. + +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 @@ -11,12 +14,17 @@ from docforge.models.object import DocObject class Module: """ - Represents a documented Python module or package. + Representation of 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: path: Dotted import path of the module. - docstring: Module-level docstring content. - members: Dictionary mapping object names to their DocObject representations. + docstring: Module-level documentation string, if present. + members: Mapping of object names to their corresponding + ``DocObject`` representations. """ def __init__( @@ -25,11 +33,11 @@ class Module: docstring: Optional[str] = None, ) -> None: """ - Initialize a new Module. + Initialize a Module instance. Args: - path: The dotted path of the module. - docstring: The module's docstring, if any. + path: Dotted import path identifying the module. + docstring: Module-level documentation text, if available. """ self.path = path self.docstring = docstring @@ -40,27 +48,32 @@ class Module: Add a documented object to the module. Args: - obj: The object to add. + obj: Documentation object to register as a top-level + member of the module. """ self.members[obj.name] = obj def get_object(self, name: str) -> DocObject: """ - Retrieve a member object by name. + Retrieve a documented object by name. Args: - name: The name of the object. + name: Name of the object to retrieve. Returns: - The requested DocObject. + The corresponding ``DocObject`` instance. + + Raises: + KeyError: If no object with the given name exists. """ return self.members[name] def get_all_objects(self) -> Iterable[DocObject]: """ - Get all top-level objects in the module. + Return all top-level documentation objects in the module. Returns: - An iterable of DocObject instances. + An iterable of ``DocObject`` instances representing the + module's public members. """ return self.members.values() diff --git a/docforge/models/object.py b/docforge/models/object.py index 666ca2b..6661387 100644 --- a/docforge/models/object.py +++ b/docforge/models/object.py @@ -1,7 +1,10 @@ """ -This module defines the DocObject class, the fundamental recursive unit of the -doc-forge documentation models. A DocObject represents a single Python entity -(class, function, method, or attribute) and its nested members. +Documentation model representing individual Python objects. + +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 @@ -9,15 +12,20 @@ from typing import Dict, Iterable, Optional class DocObject: """ - Represents a documented Python object (class, function, method, etc.). + Representation of a documented Python object. + + 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: name: Local name of the object. - kind: Type of object (e.g., 'class', 'function', 'attribute'). - path: Full dotted import path to the object. - signature: Callable signature, if applicable. - docstring: Raw docstring content extracted from the source. - members: Dictionary mapping member names to their DocObject representations. + kind: Type of object (for example ``class``, ``function``, + ``method``, or ``attribute``). + path: Fully qualified dotted path to the object. + signature: Callable signature if the object represents a callable. + docstring: Raw docstring text extracted from the source code. + members: Mapping of member names to child ``DocObject`` instances. """ def __init__( @@ -29,48 +37,54 @@ class DocObject: docstring: Optional[str] = None, ) -> None: """ - Initialize a new DocObject. + Initialize a DocObject instance. Args: - name: The local name of the object. - kind: The kind of object (e.g., 'class', 'function'). - path: The full dotted path to the object. - signature: The object's signature (for callable objects). - docstring: The object's docstring, if any. + name: Local name of the object. + kind: Object type identifier (for example ``class`` or ``function``). + path: Fully qualified dotted path of the object. + signature: Callable signature if applicable. + docstring: Documentation string associated with the object. """ self.name = name self.kind = kind self.path = path self.signature = signature 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 member to this object (e.g., a method to a class). + Add a child documentation object. + + This is typically used when attaching methods to classes or + nested objects to their parent containers. Args: - obj: The child DocObject to add. + obj: Documentation object to add as a member. """ self.members[obj.name] = obj - def get_member(self, name: str) -> 'DocObject': + def get_member(self, name: str) -> "DocObject": """ - Retrieve a child member by name. + Retrieve a member object by name. Args: - name: The name of the member. + name: Name of the member to retrieve. Returns: - The requested DocObject. + The corresponding ``DocObject`` instance. + + Raises: + KeyError: If the member does not exist. """ return self.members[name] - def get_all_members(self) -> Iterable['DocObject']: + def get_all_members(self) -> Iterable["DocObject"]: """ - Get all members of this object. + Return all child members of the object. Returns: - An iterable of child DocObject instances. + An iterable of ``DocObject`` instances representing nested members. """ return self.members.values() diff --git a/docforge/models/project.py b/docforge/models/project.py index 81c036f..3249cf6 100644 --- a/docforge/models/project.py +++ b/docforge/models/project.py @@ -1,6 +1,9 @@ """ -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 @@ -10,29 +13,32 @@ from docforge.models.module import Module class Project: """ - Represents a documentation project, serving as a container for modules. + Representation of a documentation project. + + A ``Project`` serves as the root container for all modules discovered during + introspection. Each module is stored by its dotted import path. Attributes: name: Name of the project. - modules: Dictionary mapping module paths to Module instances. + modules: Mapping of module paths to ``Module`` instances. """ def __init__(self, name: str) -> None: """ - Initialize a new Project. + Initialize a Project instance. Args: - name: The name of the project. + name: Name used to identify the documentation project. """ self.name = name self.modules: Dict[str, Module] = {} def add_module(self, module: Module) -> None: """ - Add a module to the project. + Register a module in the project. Args: - module: The module to add. + module: Module instance to add to the project. """ self.modules[module.path] = module @@ -41,27 +47,30 @@ class Project: Retrieve a module by its dotted path. Args: - path: The dotted path of the module (e.g., 'pkg.mod'). + path: Fully qualified dotted module path (for example ``pkg.module``). Returns: - The requested Module. + The corresponding ``Module`` instance. + + Raises: + KeyError: If the module does not exist in the project. """ return self.modules[path] def get_all_modules(self) -> Iterable[Module]: """ - Get all modules in the project. + Return all modules contained in the project. Returns: - An iterable of Module objects. + An iterable of ``Module`` instances. """ return self.modules.values() def get_module_list(self) -> list[str]: """ - Get the list of all module dotted paths. + Return the list of module import paths. Returns: - 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()) \ No newline at end of file diff --git a/docforge/nav/__init__.py b/docforge/nav/__init__.py index 7a2aa94..f9fd853 100644 --- a/docforge/nav/__init__.py +++ b/docforge/nav/__init__.py @@ -1,17 +1,26 @@ """ -# Navigation Layer +Navigation layer for doc-forge. -The `docforge.nav` package manages the mapping between the logical documentation -structure and the physical files on disk. +The ``docforge.nav`` package manages the relationship between the logical +documentation structure defined by the user and the physical documentation +files generated on disk. -## 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`. +Workflow +-------- -This abstraction allows doc-forge to support complex grouping and ordering -independently of the source code's physical layout. +1. **Specification** – Users define navigation intent in ``docforge.nav.yml``. +2. **Resolution** – ``resolve_nav`` expands patterns and matches them against + 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 diff --git a/docforge/nav/mkdocs.py b/docforge/nav/mkdocs.py index d304cf8..b053341 100644 --- a/docforge/nav/mkdocs.py +++ b/docforge/nav/mkdocs.py @@ -1,7 +1,9 @@ """ -This module provides the MkDocsNavEmitter, which converts a ResolvedNav instance -into the specific YAML-ready list structure expected by the MkDocs 'nav' -configuration. +MkDocs navigation emitter. + +This module provides the ``MkDocsNavEmitter`` class, which converts a +``ResolvedNav`` instance into the navigation structure required by the +MkDocs ``nav`` configuration. """ from pathlib import Path @@ -12,19 +14,24 @@ from docforge.nav.resolver import ResolvedNav class MkDocsNavEmitter: """ - Emitter responsible for transforming a ResolvedNav into an MkDocs-compatible - navigation structure. + Emit MkDocs navigation structures from resolved navigation data. + + 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]]: """ - Generate a list of navigation entries for mkdocs.yml. + Generate a navigation structure for ``mkdocs.yml``. Args: - nav: The resolved navigation data. + nav: Resolved navigation data describing documentation groups + and their associated Markdown files. Returns: - A list of dictionary mappings representing the MkDocs navigation. + A list of dictionaries representing the MkDocs navigation layout. + Each dictionary maps a navigation label to a page or a list of + pages. """ result: List[Dict[str, Any]] = [] @@ -45,16 +52,18 @@ class MkDocsNavEmitter: def _to_relative(self, path: Path, docs_root: Path | None) -> str: """ - Convert a filesystem path to a path relative to the documentation root. - This handles both absolute and relative filesystem paths, ensuring the - output is compatible with MkDocs navigation requirements. + Convert a filesystem path into a documentation-relative path. + + This method normalizes paths so they can be used in MkDocs navigation. + It handles both absolute and relative filesystem paths and ensures the + resulting path is relative to the documentation root. Args: - path: The path to convert. - docs_root: The root directory for documentation. + path: Filesystem path to convert. + docs_root: Root directory of the documentation sources. Returns: - A string representing the relative POSIX-style path. + POSIX-style path relative to the documentation root. """ if docs_root and path.is_absolute(): try: @@ -67,6 +76,6 @@ class MkDocsNavEmitter: docs_root_str = docs_root.as_posix() if path_str.startswith(docs_root_str + "/"): return path_str[len(docs_root_str) + 1:] - + # Fallback for other cases return path.as_posix().split("/docs/", 1)[-1] diff --git a/docforge/nav/resolver.py b/docforge/nav/resolver.py index ee97617..e1911a6 100644 --- a/docforge/nav/resolver.py +++ b/docforge/nav/resolver.py @@ -1,7 +1,8 @@ """ -This module contains the logic for resolving a NavSpec against the physical -filesystem. It expands globs and validates that all referenced documents -actually exist on disk. +Navigation resolution utilities. + +This module resolves a ``NavSpec`` against the filesystem by expanding glob +patterns and validating that referenced documentation files exist. """ from pathlib import Path @@ -14,12 +15,15 @@ from docforge.nav.spec import NavSpec class ResolvedNav: """ - Represents a navigation structure where all patterns and paths have been - resolved against the actual filesystem contents. + Resolved navigation structure. + + A ``ResolvedNav`` represents navigation data after glob patterns have been + expanded and paths validated against the filesystem. Attributes: - home: Resolved relative path to the home page. - groups: Mapping of group titles to lists of absolute or relative Path objects. + home: Relative path to the documentation home page. + groups: Mapping of navigation group titles to lists of resolved + documentation file paths. """ def __init__( @@ -32,9 +36,9 @@ class ResolvedNav: Initialize a ResolvedNav instance. Args: - home: The relative path to the project home page. - groups: A mapping of group names to their resolved filesystem paths. - docs_root: The root documentation directory. + home: Relative path to the home page within the documentation root. + groups: Mapping of group titles to resolved documentation file paths. + docs_root: Root directory of the documentation source files. """ self.home = home self.groups = groups @@ -42,15 +46,20 @@ class ResolvedNav: def all_files(self) -> Iterable[Path]: """ - Get an iterable of all resolved files in the navigation structure. + Iterate over all files referenced by the navigation structure. Returns: - An iterable of Path objects. + An iterable of ``Path`` objects representing documentation files. + + Raises: + RuntimeError: If the home page is defined but the documentation + root is not available for resolution. """ if self.home: if self._docs_root is None: raise RuntimeError("docs_root is required to resolve home path") yield self._docs_root / self.home + for paths in self.groups.values(): for p in paths: yield p @@ -61,34 +70,37 @@ def resolve_nav( docs_root: Path, ) -> ResolvedNav: """ - Create a ResolvedNav by processing a NavSpec against the filesystem. - This expands globs and validates the existence of referenced files. + Resolve a navigation specification against the filesystem. + + The function expands glob patterns defined in a ``NavSpec`` and verifies + that referenced documentation files exist within the documentation root. Args: - spec: The navigation specification to resolve. - docs_root: The root directory for documentation files. + spec: Navigation specification describing documentation layout. + docs_root: Root directory containing documentation Markdown files. Returns: - A ResolvedNav instance. + A ``ResolvedNav`` instance containing validated navigation paths. Raises: - FileNotFoundError: If a pattern doesn't match any files or the docs_root doesn't exist. + FileNotFoundError: If the documentation root does not exist or a + navigation pattern does not match any files. """ if not docs_root.exists(): raise FileNotFoundError(docs_root) def resolve_pattern(pattern: str) -> List[Path]: """ - Resolve a single glob pattern relative to the docs_root. + Resolve a glob pattern relative to the documentation root. Args: - pattern: The glob pattern to resolve. + pattern: Glob pattern used to match documentation files. Returns: - A sorted list of matching Path objects. + A sorted list of matching ``Path`` objects. Raises: - FileNotFoundError: If the pattern doesn't match any files. + FileNotFoundError: If the pattern does not match any files. """ full = docs_root / pattern matches = sorted( @@ -100,7 +112,7 @@ def resolve_nav( return matches - # Resolve home + # Resolve home page home: str | None = None if spec.home: home_path = docs_root / spec.home @@ -108,7 +120,7 @@ def resolve_nav( raise FileNotFoundError(spec.home) home = spec.home - # Resolve groups + # Resolve navigation groups resolved_groups: Dict[str, List[Path]] = {} for group, patterns in spec.groups.items(): diff --git a/docforge/nav/spec.py b/docforge/nav/spec.py index c7cc784..b3c8a51 100644 --- a/docforge/nav/spec.py +++ b/docforge/nav/spec.py @@ -1,7 +1,9 @@ """ -This module defines the NavSpec class, which represents the user's intent for -documentation navigation as defined in a YAML specification (usually -docforge.nav.yml). +Navigation specification model. + +This module defines the ``NavSpec`` class, which represents the navigation +structure defined by the user in the doc-forge navigation specification +(typically ``docforge.nav.yml``). """ from pathlib import Path @@ -12,11 +14,16 @@ import yaml class NavSpec: """ - Parsed representation of the docforge navigation specification file. + Parsed representation of a navigation specification. + + A ``NavSpec`` describes the intended documentation navigation layout before + it is resolved against the filesystem. Attributes: - home: Path to the home document (e.g., 'index.md'). - groups: Mapping of group titles to lists of path patterns/globs. + home: Relative path to the documentation home page (for example + ``index.md``). + groups: Mapping of navigation group titles to lists of file patterns + or glob expressions. """ def __init__( @@ -25,11 +32,12 @@ class NavSpec: groups: Dict[str, List[str]], ) -> None: """ - Initialize a NavSpec. + Initialize a NavSpec instance. Args: - home: The path to the home document. - groups: A mapping of group names to lists of path patterns (globs). + home: Relative path to the home document. + groups: Mapping of group names to lists of path patterns + (glob expressions). """ self.home = home self.groups = groups @@ -37,17 +45,18 @@ class NavSpec: @classmethod def load(cls, path: Path) -> "NavSpec": """ - Load a NavSpec from a YAML file. + Load a navigation specification from a YAML file. Args: - path: The filesystem path to the YAML file. + path: Filesystem path to the navigation specification file. Returns: - A NavSpec instance. + A ``NavSpec`` instance representing the parsed configuration. Raises: - FileNotFoundError: If the path does not exist. - ValueError: If the file content is not a valid NavSpec mapping. + FileNotFoundError: If the specified file does not exist. + ValueError: If the file contents are not a valid navigation + specification. """ if not path.exists(): raise FileNotFoundError(path) @@ -78,33 +87,45 @@ class NavSpec: def all_patterns(self) -> List[str]: """ - Get all path patterns referenced in the specification. + Return all path patterns referenced by the specification. Returns: - A list of all patterns (home plus all groups). + A list containing the home document (if defined) and all + group pattern entries. """ patterns: List[str] = [] + if self.home: patterns.append(self.home) + for items in self.groups.values(): patterns.extend(items) + return patterns def load_nav_spec(path: Path) -> NavSpec: """ - Utility function to load a NavSpec from a file. + Load a navigation specification file. + + This helper function reads a YAML navigation file and constructs a + corresponding ``NavSpec`` instance. Args: path: Path to the navigation specification file. Returns: - A loaded NavSpec instance. + A ``NavSpec`` instance representing the parsed specification. + + Raises: + FileNotFoundError: If the specification file does not exist. + ValueError: If the YAML structure is invalid. """ if not path.exists(): raise FileNotFoundError(path) data = yaml.safe_load(path.read_text(encoding="utf-8")) + if not isinstance(data, dict): raise ValueError("Nav spec must be a YAML mapping") diff --git a/docforge/renderers/__init__.py b/docforge/renderers/__init__.py index e2dc17a..85bdca2 100644 --- a/docforge/renderers/__init__.py +++ b/docforge/renderers/__init__.py @@ -1,20 +1,34 @@ """ -# 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 +models into files formatted for specific documentation systems. -## Current Implementations +--- -- **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 +for documentation tools or machine interfaces. -To add a new renderer, implement the `DocRenderer` protocol defined in -`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 diff --git a/docforge/renderers/base.py b/docforge/renderers/base.py index e688803..43835fe 100644 --- a/docforge/renderers/base.py +++ b/docforge/renderers/base.py @@ -1,7 +1,9 @@ """ -This module defines the base interfaces and configuration containers for -doc-forge renderers. All renderer implementations should adhere to the -DocRenderer protocol. +Renderer base interfaces and configuration models. + +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 @@ -14,12 +16,22 @@ class RendererConfig: """ Configuration container for documentation renderers. - Args: - out_dir: The directory where documentation files should be written. - project: The introspected project models to be rendered. + A ``RendererConfig`` instance groups together the project model and the + output directory used during rendering. + + Attributes: + out_dir: Directory where generated documentation files will be written. + project: Documentation project model to be rendered. """ def __init__(self, out_dir: Path, project: Project) -> None: + """ + Initialize a RendererConfig instance. + + Args: + out_dir: Target directory where documentation files should be written. + project: Introspected project model to render. + """ self.out_dir = out_dir self.project = project @@ -27,6 +39,9 @@ class RendererConfig: class DocRenderer(Protocol): """ 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 @@ -37,10 +52,11 @@ class DocRenderer(Protocol): out_dir: Path, ) -> None: """ - Generate renderer-specific source files for the given project. + Generate renderer-specific documentation sources. Args: - project: The project models containing modules and objects. - out_dir: Target directory for the generated files. + project: Project model containing modules and documentation objects. + out_dir: Directory where generated documentation sources + should be written. """ ... diff --git a/docforge/renderers/mcp_renderer.py b/docforge/renderers/mcp_renderer.py index 58ca317..d23d913 100644 --- a/docforge/renderers/mcp_renderer.py +++ b/docforge/renderers/mcp_renderer.py @@ -7,18 +7,25 @@ from docforge.models import Project, Module, DocObject class MCPRenderer: """ - Renderer that emits MCP-native JSON resources from docforge models. + Renderer that generates MCP-compatible documentation resources. + + This renderer converts doc-forge project models into structured JSON + resources suitable for consumption by systems implementing the Model + Context Protocol (MCP). """ name = "mcp" def generate_sources(self, project: Project, out_dir: Path) -> None: """ - Generate MCP-compatible JSON resources and navigation for the project. + Generate MCP documentation resources for a project. + + The renderer serializes each module into a JSON resource and produces + supporting metadata files such as ``nav.json`` and ``index.json``. Args: - project: The project model to render. - out_dir: Target directory for the generated JSON files. + project: Documentation project model to render. + out_dir: Directory where MCP resources will be written. """ modules_dir = out_dir / "modules" modules_dir.mkdir(parents=True, exist_ok=True) @@ -54,11 +61,11 @@ class MCPRenderer: def _write_module(self, module: Module, modules_dir: Path) -> None: """ - Serialize a module into an MCP JSON resource on disk. + Serialize a module into an MCP resource file. Args: - module: The module instance to serialize. - modules_dir: The directory where the module JSON file should be written. + module: Module instance to serialize. + modules_dir: Directory where module JSON files are stored. """ payload = { "module": module.path, @@ -71,13 +78,13 @@ class MCPRenderer: def _render_module(self, module: Module) -> Dict: """ - Render a Module into MCP-friendly structured data. + Convert a Module model into MCP-compatible structured data. Args: - module: The module instance to render. + module: Module instance to convert. Returns: - A dictionary following the MCP documentation resource schema. + Dictionary representing the module and its documented objects. """ data: Dict = { "path": module.path, @@ -92,13 +99,13 @@ class MCPRenderer: def _render_object(self, obj: DocObject) -> Dict: """ - Recursively render a DocObject into structured MCP data. + Recursively convert a DocObject into structured MCP data. Args: - obj: The documented object (class, func, etc.) to render. + obj: Documentation object to convert. Returns: - A dictionary representing the object and its members. + Dictionary describing the object and any nested members. """ data: Dict = { "name": obj.name, @@ -119,4 +126,13 @@ class MCPRenderer: @staticmethod def _json(data: Dict) -> str: + """ + Serialize data to formatted JSON. + + Args: + data: Dictionary to serialize. + + Returns: + JSON string formatted with indentation and UTF-8 compatibility. + """ return json.dumps(data, indent=2, ensure_ascii=False) diff --git a/docforge/renderers/mkdocs_renderer.py b/docforge/renderers/mkdocs_renderer.py index b851812..5e85143 100644 --- a/docforge/renderers/mkdocs_renderer.py +++ b/docforge/renderers/mkdocs_renderer.py @@ -1,12 +1,16 @@ """ -MkDocsRenderer +MkDocs renderer implementation. -Generates Markdown source files compatible with MkDocs Material -and mkdocstrings, ensuring: +This module defines the ``MkDocsRenderer`` class, which generates Markdown +documentation sources compatible with MkDocs Material and the mkdocstrings +plugin. -- Root index.md always exists -- Parent package indexes are created automatically -- Child modules are linked in parent index files +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 @@ -15,8 +19,10 @@ from docforge.models import Project, Module class MkDocsRenderer: """ - Renderer that generates Markdown source files formatted for the MkDocs - 'mkdocstrings' plugin. + Renderer that produces Markdown documentation for MkDocs. + + Generated pages use mkdocstrings directives to reference Python modules, + allowing MkDocs to render API documentation dynamically. """ name = "mkdocs" @@ -24,6 +30,7 @@ class MkDocsRenderer: # ------------------------- # Public API # ------------------------- + def generate_sources( self, project: Project, @@ -31,13 +38,17 @@ class MkDocsRenderer: module_is_source: bool | None = None, ) -> None: """ - Produce a set of Markdown files in the output directory based on the - provided Project models. + Generate Markdown documentation files for a project. + + This method renders a documentation structure from the provided + project model and writes the resulting Markdown files to the + specified output directory. Args: - project: The project models to render. - out_dir: Target directory for documentation files. - module_is_source: Module is the source folder and to be treated as the root folder. + project: Project model containing modules to document. + out_dir: Directory where generated Markdown files will be written. + module_is_source: 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) @@ -45,7 +56,7 @@ class MkDocsRenderer: modules = list(project.get_all_modules()) paths = {m.path for m in modules} - # Package detection (level-agnostic) + # Detect packages (modules with children) packages = { p for p in paths if any(other.startswith(p + ".") for other in paths) @@ -59,9 +70,82 @@ class MkDocsRenderer: 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 model containing documentation metadata. + docs_dir: Directory containing generated documentation sources. + module_is_source: 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 # ------------------------- + + def _find_root_module(self, project: Project) -> Module | None: + """ + Locate the root module corresponding to the project name. + + Args: + project: Project model to inspect. + + Returns: + 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, @@ -70,15 +154,20 @@ class MkDocsRenderer: module_is_source: bool | None = None, ) -> None: """ - Write a single module's documentation file. Packages are written as - 'index.md' inside their respective directories. + 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: The module to write. - packages: A set of module paths that are identified as packages. - out_dir: The base output directory. - module_is_source: Module is the source folder and to be treated as the root folder. + module: Module to render. + packages: Set of module paths identified as packages. + out_dir: Base directory for generated documentation files. + module_is_source: Whether the module acts as the documentation + root directory. """ + parts = module.path.split(".") if module_is_source: @@ -87,15 +176,15 @@ class MkDocsRenderer: module_name, parts = parts[0], parts if module.path in packages: - # Package → directory/index.md dir_path = out_dir.joinpath(*parts) dir_path.mkdir(parents=True, exist_ok=True) + md_path = dir_path / "index.md" link_target = f"{parts[-1]}/" if parts else None else: - # Leaf module → parent_dir/.md dir_path = out_dir.joinpath(*parts[:-1]) dir_path.mkdir(parents=True, exist_ok=True) + md_path = dir_path / f"{parts[-1]}.md" link_target = f"{parts[-1]}.md" if parts else None @@ -110,14 +199,14 @@ class MkDocsRenderer: def _render_markdown(self, title: str, module_path: str) -> str: """ - Generate the Markdown content for a module file. + Generate Markdown content for a module documentation page. Args: - title: The display title for the page. - module_path: The dotted path of the module to document. + title: Page title displayed in the documentation. + module_path: Dotted import path of the module. Returns: - A string containing the Markdown source. + Markdown source containing a mkdocstrings directive. """ return ( f"# {title}\n\n" @@ -127,8 +216,15 @@ class MkDocsRenderer: def _ensure_root_index( self, project: Project, - out_dir: Path + out_dir: Path, ) -> None: + """ + Ensure that the root ``index.md`` page exists. + + Args: + project: Project model used for the page title. + out_dir: Documentation output directory. + """ root_index = out_dir / "index.md" if not root_index.exists(): @@ -145,16 +241,23 @@ class MkDocsRenderer: link_target: str, title: str, ) -> None: + """ + Ensure that parent package index files exist and contain links to + child modules. + + Args: + parts: Module path components. + out_dir: Documentation output directory. + link_target: Link target used in the parent index. + title: Display title for the link. + """ if len(parts) == 1: parent_index = out_dir / "index.md" - link = f"- [{title}]({link_target})\n" else: parent_dir = out_dir.joinpath(*parts[:-1]) parent_dir.mkdir(parents=True, exist_ok=True) parent_index = parent_dir / "index.md" - link = f"- [{title}]({link_target})\n" - if not parent_index.exists(): parent_title = parts[-2].replace("_", " ").title() parent_index.write_text( @@ -164,5 +267,6 @@ class MkDocsRenderer: 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") diff --git a/docforge/renderers/mkdocs_renderer.pyi b/docforge/renderers/mkdocs_renderer.pyi index 130e4dc..584e425 100644 --- a/docforge/renderers/mkdocs_renderer.pyi +++ b/docforge/renderers/mkdocs_renderer.pyi @@ -12,6 +12,13 @@ class MkDocsRenderer: 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( self, module: Module, diff --git a/docforge/servers/__init__.py b/docforge/servers/__init__.py index ec31273..228a7e3 100644 --- a/docforge/servers/__init__.py +++ b/docforge/servers/__init__.py @@ -1,5 +1,15 @@ +""" +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 __all__ = [ "MCPServer", -] \ No newline at end of file +] diff --git a/docforge/servers/mcp_server.py b/docforge/servers/mcp_server.py index 9ba34d9..a512edd 100644 --- a/docforge/servers/mcp_server.py +++ b/docforge/servers/mcp_server.py @@ -9,16 +9,21 @@ from mcp.server.fastmcp import FastMCP class MCPServer: """ - MCP server for serving a pre-built MCP documentation bundle. + MCP server for serving a pre-generated 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: """ - Initialize the MCPServer. + Initialize the MCP server. Args: - mcp_root: Path to the directory containing pre-built MCP JSON resources. - name: Name of the MCP server. + mcp_root: Directory containing the generated MCP documentation + bundle (for example ``index.json``, ``nav.json``, and + ``modules/``). + name: Identifier used for the MCP server instance. """ self.mcp_root = mcp_root self.app = FastMCP(name) @@ -32,19 +37,24 @@ class MCPServer: def _read_json(self, path: Path) -> Any: """ - Read and parse a JSON file, returning diagnostic errors if missing. + Load and parse a JSON file. + + If the file does not exist, a structured error response is returned + instead of raising an exception. Args: - path: Path to the JSON file. + path: Path to the JSON file to read. Returns: - 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(): return { "error": "not_found", "path": str(path), } + return json.loads(path.read_text(encoding="utf-8")) # ------------------------------------------------------------------ @@ -53,8 +63,16 @@ class MCPServer: def _register_resources(self) -> None: """ - Register MCP resources for index, nav, and individual modules. + Register MCP resource endpoints. + + 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") def index(): return self._read_json(self.mcp_root / "index.json") @@ -70,26 +88,35 @@ class MCPServer: ) # ------------------------------------------------------------------ - # MCP tools (optional / diagnostic) + # MCP tools # ------------------------------------------------------------------ def _register_tools(self) -> None: """ - Register high-level MCP tools for diagnostics. + Register optional MCP diagnostic tools. + + These tools provide lightweight endpoints useful for verifying that + the MCP server is operational. """ + @self.app.tool() def ping() -> str: + """Return a simple health check response.""" return "pong" # ------------------------------------------------------------------ # Server lifecycle # ------------------------------------------------------------------ - def run(self, transport: Literal["stdio", "sse", "streamable-http"] = "streamable-http") -> None: + def run( + self, + transport: Literal["stdio", "sse", "streamable-http"] = "streamable-http", + ) -> None: """ Start the MCP server. Args: - transport: MCP transport (default: streamable-http) + transport: Transport mechanism used by the MCP server. Supported + options include ``stdio``, ``sse``, and ``streamable-http``. """ self.app.run(transport=transport) diff --git a/docforge/templates/mkdocs.sample.yml b/docforge/templates/mkdocs.sample.yml index 6ff70df..3d17c33 100644 --- a/docforge/templates/mkdocs.sample.yml +++ b/docforge/templates/mkdocs.sample.yml @@ -4,16 +4,30 @@ theme: - scheme: slate primary: deep purple accent: cyan + font: text: Inter code: JetBrains Mono + features: - - navigation.tabs + # Navigation + - navigation.sections - navigation.expand - navigation.top - navigation.instant + - navigation.tracking + - navigation.indexes + + # Content - content.code.copy - content.code.annotate + - content.tabs.link + - content.action.edit + + # Search UX + - search.highlight + - search.share + - search.suggest plugins: - search @@ -31,8 +45,34 @@ plugins: annotations_path: brief show_root_heading: 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 diff --git a/mcp_docs/modules/docforge.cli.commands.json b/mcp_docs/modules/docforge.cli.commands.json index 1d5d04d..b15165b 100644 --- a/mcp_docs/modules/docforge.cli.commands.json +++ b/mcp_docs/modules/docforge.cli.commands.json @@ -37,21 +37,21 @@ "kind": "class", "path": "docforge.cli.commands.GriffeLoader", "signature": "", - "docstring": "Loads Python modules and extracts documentation using the Griffe introspection engine.", + "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.", "members": { "load_project": { "name": "load_project", "kind": "function", "path": "docforge.cli.commands.GriffeLoader.load_project", "signature": "", - "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." + "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 of dotted module import paths to load.\n project_name: Optional override for the project name. Defaults\n to the top-level name of the first module.\n skip_import_errors: If True, modules that fail to load will be\n skipped instead of raising an error.\n\nReturns:\n A populated ``Project`` instance containing the loaded modules.\n\nRaises:\n ValueError: If no module paths are provided.\n ImportError: If a module fails to load and\n ``skip_import_errors`` is False." }, "load_module": { "name": "load_module", "kind": "function", "path": "docforge.cli.commands.GriffeLoader.load_module", "signature": "", - "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." + "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: Dotted import path of the module.\n\nReturns:\n A populated ``Module`` instance." } } }, @@ -95,21 +95,21 @@ "kind": "class", "path": "docforge.cli.commands.mkdocs_utils.GriffeLoader", "signature": "", - "docstring": "Loads Python modules and extracts documentation using the Griffe introspection engine.", + "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.", "members": { "load_project": { "name": "load_project", "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.GriffeLoader.load_project", "signature": "", - "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." + "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 of dotted module import paths to load.\n project_name: Optional override for the project name. Defaults\n to the top-level name of the first module.\n skip_import_errors: If True, modules that fail to load will be\n skipped instead of raising an error.\n\nReturns:\n A populated ``Project`` instance containing the loaded modules.\n\nRaises:\n ValueError: If no module paths are provided.\n ImportError: If a module fails to load and\n ``skip_import_errors`` is False." }, "load_module": { "name": "load_module", "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.GriffeLoader.load_module", "signature": "", - "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." + "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: Dotted import path of the module.\n\nReturns:\n A populated ``Module`` instance." } } }, @@ -118,14 +118,14 @@ "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.discover_module_paths", "signature": "", - "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." + "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: Top-level package name to discover modules from.\n project_root: Root directory used to resolve module paths. If not\n provided, the current working directory is used.\n\nReturns:\n A sorted list of unique dotted module import paths.\n\nRaises:\n FileNotFoundError: If the specified package directory does not exist." }, "MkDocsRenderer": { "name": "MkDocsRenderer", "kind": "class", "path": "docforge.cli.commands.mkdocs_utils.MkDocsRenderer", "signature": "", - "docstring": "Renderer that generates Markdown source files formatted for the MkDocs\n'mkdocstrings' plugin.", + "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", @@ -139,7 +139,14 @@ "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.MkDocsRenderer.generate_sources", "signature": "", - "docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project: The project models to render.\n out_dir: Target directory for documentation files.\n module_is_source: Module is the source folder and to be treated as the root folder." + "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 model containing modules to document.\n out_dir: Directory where generated Markdown files will be written.\n module_is_source: If True, treat the specified module as the\n documentation root rather than nesting it inside a folder." + }, + "generate_readme": { + "name": "generate_readme", + "kind": "function", + "path": "docforge.cli.commands.mkdocs_utils.MkDocsRenderer.generate_readme", + "signature": "", + "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\n project root directory.\n- If False, README generation is currently not implemented.\n\nArgs:\n project: Project model containing documentation metadata.\n docs_dir: Directory containing generated documentation sources.\n module_is_source: Whether the module is treated as the project\n source root." } } }, @@ -148,28 +155,28 @@ "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.load_nav_spec", "signature": "", - "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." + "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." }, "resolve_nav": { "name": "resolve_nav", "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.resolve_nav", "signature": "", - "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." + "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." }, "MkDocsNavEmitter": { "name": "MkDocsNavEmitter", "kind": "class", "path": "docforge.cli.commands.mkdocs_utils.MkDocsNavEmitter", "signature": "", - "docstring": "Emitter responsible for transforming a ResolvedNav into an MkDocs-compatible\nnavigation structure.", + "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.", "members": { "emit": { "name": "emit", "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.MkDocsNavEmitter.emit", "signature": "", - "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." + "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." } } }, @@ -178,28 +185,28 @@ "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.generate_sources", "signature": "", - "docstring": "Generate Markdown source files for the specified module.\n\nArgs:\n module: The dotted path of the primary module to document.\n project_name: Optional override for the project name.\n docs_dir: Directory where the generated Markdown files will be written.\n module_is_source: Module is the source folder and to be treated as the root folder." + "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: Python module import path used as the entry point for\n documentation generation.\n docs_dir: Directory where the generated Markdown files will be written.\n project_name: Optional override for the project name used in\n documentation metadata.\n module_is_source: If True, treat the specified module directory as\n the project root rather than a nested module." }, "generate_config": { "name": "generate_config", "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.generate_config", "signature": "", - "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." + "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: Directory containing generated documentation Markdown files.\n nav_file: Path to the ``docforge.nav.yml`` navigation specification.\n template: Optional path to a custom MkDocs configuration template.\n If not provided, a built-in template will be used.\n out: Destination path where the generated ``mkdocs.yml`` file\n will be written.\n site_name: Display name for the generated documentation site.\n\nRaises:\n click.FileError: If the navigation specification or template\n file cannot be found." }, "build": { "name": "build", "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.build", "signature": "", - "docstring": "Build the documentation site using MkDocs.\n\nArgs:\n mkdocs_yml: Path to the mkdocs.yml configuration file." + "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 to the ``mkdocs.yml`` configuration file.\n\nRaises:\n click.ClickException: If the configuration file does not exist." }, "serve": { "name": "serve", "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.serve", "signature": "", - "docstring": "Serve the documentation site with live-reload using MkDocs.\n\nArgs:\n mkdocs_yml: Path to the mkdocs.yml configuration file." + "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 to the ``mkdocs.yml`` configuration file.\n\nRaises:\n click.ClickException: If the configuration file does not exist." } } }, @@ -229,21 +236,21 @@ "kind": "class", "path": "docforge.cli.commands.mcp_utils.GriffeLoader", "signature": "", - "docstring": "Loads Python modules and extracts documentation using the Griffe introspection engine.", + "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.", "members": { "load_project": { "name": "load_project", "kind": "function", "path": "docforge.cli.commands.mcp_utils.GriffeLoader.load_project", "signature": "", - "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." + "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 of dotted module import paths to load.\n project_name: Optional override for the project name. Defaults\n to the top-level name of the first module.\n skip_import_errors: If True, modules that fail to load will be\n skipped instead of raising an error.\n\nReturns:\n A populated ``Project`` instance containing the loaded modules.\n\nRaises:\n ValueError: If no module paths are provided.\n ImportError: If a module fails to load and\n ``skip_import_errors`` is False." }, "load_module": { "name": "load_module", "kind": "function", "path": "docforge.cli.commands.mcp_utils.GriffeLoader.load_module", "signature": "", - "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." + "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: Dotted import path of the module.\n\nReturns:\n A populated ``Module`` instance." } } }, @@ -252,14 +259,14 @@ "kind": "function", "path": "docforge.cli.commands.mcp_utils.discover_module_paths", "signature": "", - "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." + "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: Top-level package name to discover modules from.\n project_root: Root directory used to resolve module paths. If not\n provided, the current working directory is used.\n\nReturns:\n A sorted list of unique dotted module import paths.\n\nRaises:\n FileNotFoundError: If the specified package directory does not exist." }, "MCPRenderer": { "name": "MCPRenderer", "kind": "class", "path": "docforge.cli.commands.mcp_utils.MCPRenderer", "signature": "", - "docstring": "Renderer that emits MCP-native JSON resources from docforge models.", + "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).", "members": { "name": { "name": "name", @@ -273,7 +280,7 @@ "kind": "function", "path": "docforge.cli.commands.mcp_utils.MCPRenderer.generate_sources", "signature": "", - "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." + "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: Documentation project model to render.\n out_dir: Directory where MCP resources will be written." } } }, @@ -282,7 +289,7 @@ "kind": "class", "path": "docforge.cli.commands.mcp_utils.MCPServer", "signature": "", - "docstring": "MCP server for serving a pre-built MCP documentation bundle.", + "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.", "members": { "mcp_root": { "name": "mcp_root", @@ -303,7 +310,7 @@ "kind": "function", "path": "docforge.cli.commands.mcp_utils.MCPServer.run", "signature": "", - "docstring": "Start the MCP server.\n\nArgs:\n transport: MCP transport (default: streamable-http)" + "docstring": "Start the MCP server.\n\nArgs:\n transport: Transport mechanism used by the MCP server. Supported\n options include ``stdio``, ``sse``, and ``streamable-http``." } } }, @@ -312,14 +319,14 @@ "kind": "function", "path": "docforge.cli.commands.mcp_utils.generate_resources", "signature": "", - "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." + "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: Python module import path used as the entry point for\n documentation generation.\n project_name: Optional override for the project name used in\n generated documentation metadata.\n out_dir: Directory where MCP resources (index.json, nav.json,\n and module data) will be written." }, "serve": { "name": "serve", "kind": "function", "path": "docforge.cli.commands.mcp_utils.serve", "signature": "", - "docstring": "Serve MCP documentation from a pre-built bundle.\n\nArgs:\n module: The dotted path of the primary module to serve.\n mcp_root: Path to the directory containing index.json, nav.json, and modules/." + "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: Python module import path used to identify the served\n documentation instance.\n mcp_root: Path to the directory containing the MCP documentation\n bundle (index.json, nav.json, and modules/).\n\nRaises:\n click.ClickException: If the MCP documentation bundle is missing\n required files or directories." } } }, @@ -334,22 +341,22 @@ "name": "build", "kind": "function", "path": "docforge.cli.commands.build", - "signature": "", - "docstring": "Build documentation (MkDocs site or MCP resources).\n\nThis command orchestrates the full build process:\n1. Introspects the code (Griffe)\n2. Renders sources (MkDocs Markdown or MCP JSON)\n3. (MkDocs only) Generates config and runs the final site build.\n\nArgs:\n mcp: Use the MCP documentation builder.\n mkdocs: Use the MkDocs documentation builder.\n module_is_source: Module is the source folder and to be treated as the root folder.\n module: The dotted path of the module to the document.\n project_name: Optional override for the project name.\n site_name: (MkDocs) The site display name. Defaults to module name.\n docs_dir: (MkDocs) Target directory for Markdown sources.\n nav_file: (MkDocs) Path to the docforge.nav.yml specification.\n template: (MkDocs) Optional custom mkdocs.yml template.\n mkdocs_yml: (MkDocs) Target path for the generated mkdocs.yml.\n out_dir: (MCP) Target directory for MCP JSON resources." + "signature": "", + "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: Enable MCP documentation generation.\n mkdocs: Enable MkDocs documentation generation.\n module_is_source: Treat the specified module directory as the\n project root.\n module: Python module import path to document.\n project_name: Optional override for the project name.\n site_name: Display name for the MkDocs site.\n docs_dir: Directory where Markdown documentation sources\n will be generated.\n nav_file: Path to the navigation specification file.\n template: Optional custom MkDocs configuration template.\n mkdocs_yml: Output path for the generated MkDocs configuration.\n out_dir: Output directory for generated MCP resources.\n\nRaises:\n click.UsageError: If required options are missing or conflicting." }, "serve": { "name": "serve", "kind": "function", "path": "docforge.cli.commands.serve", - "signature": "", - "docstring": "Serve documentation (MkDocs or MCP).\n\nArgs:\n mcp: Serve MCP resources via an MCP server.\n mkdocs: Serve the MkDocs site using the built-in development server.\n module: The dotted path of the module to serve.\n mkdocs_yml: (MkDocs) Path to the mkdocs.yml configuration.\n out_dir: (MCP) Path to the mcp_docs/ directory." + "signature": "", + "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: Serve documentation using the MCP server.\n mkdocs: Serve the MkDocs development site.\n module: Python module import path to serve via MCP.\n mkdocs_yml: Path to the MkDocs configuration file.\n out_dir: Root directory containing MCP documentation resources.\n\nRaises:\n click.UsageError: If invalid or conflicting options are provided." }, "tree": { "name": "tree", "kind": "function", "path": "docforge.cli.commands.tree", - "signature": "", - "docstring": "Visualize the project structure in the terminal.\n\nArgs:\n module: The module import path to recursively introspect.\n project_name: Optional override for the project name shown at the root." + "signature": "", + "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: Python module import path to introspect.\n project_name: Optional name to display as the project root." }, "Group": { "name": "Group", diff --git a/mcp_docs/modules/docforge.cli.json b/mcp_docs/modules/docforge.cli.json index 51c5aad..c7bb736 100644 --- a/mcp_docs/modules/docforge.cli.json +++ b/mcp_docs/modules/docforge.cli.json @@ -2,14 +2,14 @@ "module": "docforge.cli", "content": { "path": "docforge.cli", - "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.", + "docstring": "Command 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\nTypical usage\n-------------\n\nThe CLI is normally invoked through the installed command:\n\n doc-forge [options]\n\nProgrammatic invocation is also possible:\n\n from docforge.cli import main\n main()\n\n---", "objects": { "main": { "name": "main", "kind": "module", "path": "docforge.cli.main", "signature": null, - "docstring": "Main entry point for the doc-forge CLI. This module delegates all command\nexecution to docforge.cli.commands.", + "docstring": "Command-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``.", "members": { "cli": { "name": "cli", @@ -22,8 +22,8 @@ "name": "main", "kind": "function", "path": "docforge.cli.main.main", - "signature": "", - "docstring": "CLI Entry point. Boots the click application." + "signature": "", + "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." } } }, @@ -67,21 +67,21 @@ "kind": "class", "path": "docforge.cli.commands.GriffeLoader", "signature": "", - "docstring": "Loads Python modules and extracts documentation using the Griffe introspection engine.", + "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.", "members": { "load_project": { "name": "load_project", "kind": "function", "path": "docforge.cli.commands.GriffeLoader.load_project", "signature": "", - "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." + "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 of dotted module import paths to load.\n project_name: Optional override for the project name. Defaults\n to the top-level name of the first module.\n skip_import_errors: If True, modules that fail to load will be\n skipped instead of raising an error.\n\nReturns:\n A populated ``Project`` instance containing the loaded modules.\n\nRaises:\n ValueError: If no module paths are provided.\n ImportError: If a module fails to load and\n ``skip_import_errors`` is False." }, "load_module": { "name": "load_module", "kind": "function", "path": "docforge.cli.commands.GriffeLoader.load_module", "signature": "", - "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." + "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: Dotted import path of the module.\n\nReturns:\n A populated ``Module`` instance." } } }, @@ -125,21 +125,21 @@ "kind": "class", "path": "docforge.cli.commands.mkdocs_utils.GriffeLoader", "signature": "", - "docstring": "Loads Python modules and extracts documentation using the Griffe introspection engine.", + "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.", "members": { "load_project": { "name": "load_project", "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.GriffeLoader.load_project", "signature": "", - "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." + "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 of dotted module import paths to load.\n project_name: Optional override for the project name. Defaults\n to the top-level name of the first module.\n skip_import_errors: If True, modules that fail to load will be\n skipped instead of raising an error.\n\nReturns:\n A populated ``Project`` instance containing the loaded modules.\n\nRaises:\n ValueError: If no module paths are provided.\n ImportError: If a module fails to load and\n ``skip_import_errors`` is False." }, "load_module": { "name": "load_module", "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.GriffeLoader.load_module", "signature": "", - "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." + "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: Dotted import path of the module.\n\nReturns:\n A populated ``Module`` instance." } } }, @@ -148,14 +148,14 @@ "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.discover_module_paths", "signature": "", - "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." + "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: Top-level package name to discover modules from.\n project_root: Root directory used to resolve module paths. If not\n provided, the current working directory is used.\n\nReturns:\n A sorted list of unique dotted module import paths.\n\nRaises:\n FileNotFoundError: If the specified package directory does not exist." }, "MkDocsRenderer": { "name": "MkDocsRenderer", "kind": "class", "path": "docforge.cli.commands.mkdocs_utils.MkDocsRenderer", "signature": "", - "docstring": "Renderer that generates Markdown source files formatted for the MkDocs\n'mkdocstrings' plugin.", + "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", @@ -169,7 +169,14 @@ "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.MkDocsRenderer.generate_sources", "signature": "", - "docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project: The project models to render.\n out_dir: Target directory for documentation files.\n module_is_source: Module is the source folder and to be treated as the root folder." + "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 model containing modules to document.\n out_dir: Directory where generated Markdown files will be written.\n module_is_source: If True, treat the specified module as the\n documentation root rather than nesting it inside a folder." + }, + "generate_readme": { + "name": "generate_readme", + "kind": "function", + "path": "docforge.cli.commands.mkdocs_utils.MkDocsRenderer.generate_readme", + "signature": "", + "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\n project root directory.\n- If False, README generation is currently not implemented.\n\nArgs:\n project: Project model containing documentation metadata.\n docs_dir: Directory containing generated documentation sources.\n module_is_source: Whether the module is treated as the project\n source root." } } }, @@ -178,28 +185,28 @@ "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.load_nav_spec", "signature": "", - "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." + "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." }, "resolve_nav": { "name": "resolve_nav", "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.resolve_nav", "signature": "", - "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." + "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." }, "MkDocsNavEmitter": { "name": "MkDocsNavEmitter", "kind": "class", "path": "docforge.cli.commands.mkdocs_utils.MkDocsNavEmitter", "signature": "", - "docstring": "Emitter responsible for transforming a ResolvedNav into an MkDocs-compatible\nnavigation structure.", + "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.", "members": { "emit": { "name": "emit", "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.MkDocsNavEmitter.emit", "signature": "", - "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." + "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." } } }, @@ -208,28 +215,28 @@ "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.generate_sources", "signature": "", - "docstring": "Generate Markdown source files for the specified module.\n\nArgs:\n module: The dotted path of the primary module to document.\n project_name: Optional override for the project name.\n docs_dir: Directory where the generated Markdown files will be written.\n module_is_source: Module is the source folder and to be treated as the root folder." + "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: Python module import path used as the entry point for\n documentation generation.\n docs_dir: Directory where the generated Markdown files will be written.\n project_name: Optional override for the project name used in\n documentation metadata.\n module_is_source: If True, treat the specified module directory as\n the project root rather than a nested module." }, "generate_config": { "name": "generate_config", "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.generate_config", "signature": "", - "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." + "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: Directory containing generated documentation Markdown files.\n nav_file: Path to the ``docforge.nav.yml`` navigation specification.\n template: Optional path to a custom MkDocs configuration template.\n If not provided, a built-in template will be used.\n out: Destination path where the generated ``mkdocs.yml`` file\n will be written.\n site_name: Display name for the generated documentation site.\n\nRaises:\n click.FileError: If the navigation specification or template\n file cannot be found." }, "build": { "name": "build", "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.build", "signature": "", - "docstring": "Build the documentation site using MkDocs.\n\nArgs:\n mkdocs_yml: Path to the mkdocs.yml configuration file." + "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 to the ``mkdocs.yml`` configuration file.\n\nRaises:\n click.ClickException: If the configuration file does not exist." }, "serve": { "name": "serve", "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.serve", "signature": "", - "docstring": "Serve the documentation site with live-reload using MkDocs.\n\nArgs:\n mkdocs_yml: Path to the mkdocs.yml configuration file." + "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 to the ``mkdocs.yml`` configuration file.\n\nRaises:\n click.ClickException: If the configuration file does not exist." } } }, @@ -259,21 +266,21 @@ "kind": "class", "path": "docforge.cli.commands.mcp_utils.GriffeLoader", "signature": "", - "docstring": "Loads Python modules and extracts documentation using the Griffe introspection engine.", + "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.", "members": { "load_project": { "name": "load_project", "kind": "function", "path": "docforge.cli.commands.mcp_utils.GriffeLoader.load_project", "signature": "", - "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." + "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 of dotted module import paths to load.\n project_name: Optional override for the project name. Defaults\n to the top-level name of the first module.\n skip_import_errors: If True, modules that fail to load will be\n skipped instead of raising an error.\n\nReturns:\n A populated ``Project`` instance containing the loaded modules.\n\nRaises:\n ValueError: If no module paths are provided.\n ImportError: If a module fails to load and\n ``skip_import_errors`` is False." }, "load_module": { "name": "load_module", "kind": "function", "path": "docforge.cli.commands.mcp_utils.GriffeLoader.load_module", "signature": "", - "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." + "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: Dotted import path of the module.\n\nReturns:\n A populated ``Module`` instance." } } }, @@ -282,14 +289,14 @@ "kind": "function", "path": "docforge.cli.commands.mcp_utils.discover_module_paths", "signature": "", - "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." + "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: Top-level package name to discover modules from.\n project_root: Root directory used to resolve module paths. If not\n provided, the current working directory is used.\n\nReturns:\n A sorted list of unique dotted module import paths.\n\nRaises:\n FileNotFoundError: If the specified package directory does not exist." }, "MCPRenderer": { "name": "MCPRenderer", "kind": "class", "path": "docforge.cli.commands.mcp_utils.MCPRenderer", "signature": "", - "docstring": "Renderer that emits MCP-native JSON resources from docforge models.", + "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).", "members": { "name": { "name": "name", @@ -303,7 +310,7 @@ "kind": "function", "path": "docforge.cli.commands.mcp_utils.MCPRenderer.generate_sources", "signature": "", - "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." + "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: Documentation project model to render.\n out_dir: Directory where MCP resources will be written." } } }, @@ -312,7 +319,7 @@ "kind": "class", "path": "docforge.cli.commands.mcp_utils.MCPServer", "signature": "", - "docstring": "MCP server for serving a pre-built MCP documentation bundle.", + "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.", "members": { "mcp_root": { "name": "mcp_root", @@ -333,7 +340,7 @@ "kind": "function", "path": "docforge.cli.commands.mcp_utils.MCPServer.run", "signature": "", - "docstring": "Start the MCP server.\n\nArgs:\n transport: MCP transport (default: streamable-http)" + "docstring": "Start the MCP server.\n\nArgs:\n transport: Transport mechanism used by the MCP server. Supported\n options include ``stdio``, ``sse``, and ``streamable-http``." } } }, @@ -342,14 +349,14 @@ "kind": "function", "path": "docforge.cli.commands.mcp_utils.generate_resources", "signature": "", - "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." + "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: Python module import path used as the entry point for\n documentation generation.\n project_name: Optional override for the project name used in\n generated documentation metadata.\n out_dir: Directory where MCP resources (index.json, nav.json,\n and module data) will be written." }, "serve": { "name": "serve", "kind": "function", "path": "docforge.cli.commands.mcp_utils.serve", "signature": "", - "docstring": "Serve MCP documentation from a pre-built bundle.\n\nArgs:\n module: The dotted path of the primary module to serve.\n mcp_root: Path to the directory containing index.json, nav.json, and modules/." + "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: Python module import path used to identify the served\n documentation instance.\n mcp_root: Path to the directory containing the MCP documentation\n bundle (index.json, nav.json, and modules/).\n\nRaises:\n click.ClickException: If the MCP documentation bundle is missing\n required files or directories." } } }, @@ -364,22 +371,22 @@ "name": "build", "kind": "function", "path": "docforge.cli.commands.build", - "signature": "", - "docstring": "Build documentation (MkDocs site or MCP resources).\n\nThis command orchestrates the full build process:\n1. Introspects the code (Griffe)\n2. Renders sources (MkDocs Markdown or MCP JSON)\n3. (MkDocs only) Generates config and runs the final site build.\n\nArgs:\n mcp: Use the MCP documentation builder.\n mkdocs: Use the MkDocs documentation builder.\n module_is_source: Module is the source folder and to be treated as the root folder.\n module: The dotted path of the module to the document.\n project_name: Optional override for the project name.\n site_name: (MkDocs) The site display name. Defaults to module name.\n docs_dir: (MkDocs) Target directory for Markdown sources.\n nav_file: (MkDocs) Path to the docforge.nav.yml specification.\n template: (MkDocs) Optional custom mkdocs.yml template.\n mkdocs_yml: (MkDocs) Target path for the generated mkdocs.yml.\n out_dir: (MCP) Target directory for MCP JSON resources." + "signature": "", + "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: Enable MCP documentation generation.\n mkdocs: Enable MkDocs documentation generation.\n module_is_source: Treat the specified module directory as the\n project root.\n module: Python module import path to document.\n project_name: Optional override for the project name.\n site_name: Display name for the MkDocs site.\n docs_dir: Directory where Markdown documentation sources\n will be generated.\n nav_file: Path to the navigation specification file.\n template: Optional custom MkDocs configuration template.\n mkdocs_yml: Output path for the generated MkDocs configuration.\n out_dir: Output directory for generated MCP resources.\n\nRaises:\n click.UsageError: If required options are missing or conflicting." }, "serve": { "name": "serve", "kind": "function", "path": "docforge.cli.commands.serve", - "signature": "", - "docstring": "Serve documentation (MkDocs or MCP).\n\nArgs:\n mcp: Serve MCP resources via an MCP server.\n mkdocs: Serve the MkDocs site using the built-in development server.\n module: The dotted path of the module to serve.\n mkdocs_yml: (MkDocs) Path to the mkdocs.yml configuration.\n out_dir: (MCP) Path to the mcp_docs/ directory." + "signature": "", + "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: Serve documentation using the MCP server.\n mkdocs: Serve the MkDocs development site.\n module: Python module import path to serve via MCP.\n mkdocs_yml: Path to the MkDocs configuration file.\n out_dir: Root directory containing MCP documentation resources.\n\nRaises:\n click.UsageError: If invalid or conflicting options are provided." }, "tree": { "name": "tree", "kind": "function", "path": "docforge.cli.commands.tree", - "signature": "", - "docstring": "Visualize the project structure in the terminal.\n\nArgs:\n module: The module import path to recursively introspect.\n project_name: Optional override for the project name shown at the root." + "signature": "", + "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: Python module import path to introspect.\n project_name: Optional name to display as the project root." }, "Group": { "name": "Group", @@ -423,21 +430,21 @@ "kind": "class", "path": "docforge.cli.mcp_utils.GriffeLoader", "signature": "", - "docstring": "Loads Python modules and extracts documentation using the Griffe introspection engine.", + "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.", "members": { "load_project": { "name": "load_project", "kind": "function", "path": "docforge.cli.mcp_utils.GriffeLoader.load_project", "signature": "", - "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." + "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 of dotted module import paths to load.\n project_name: Optional override for the project name. Defaults\n to the top-level name of the first module.\n skip_import_errors: If True, modules that fail to load will be\n skipped instead of raising an error.\n\nReturns:\n A populated ``Project`` instance containing the loaded modules.\n\nRaises:\n ValueError: If no module paths are provided.\n ImportError: If a module fails to load and\n ``skip_import_errors`` is False." }, "load_module": { "name": "load_module", "kind": "function", "path": "docforge.cli.mcp_utils.GriffeLoader.load_module", "signature": "", - "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." + "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: Dotted import path of the module.\n\nReturns:\n A populated ``Module`` instance." } } }, @@ -446,14 +453,14 @@ "kind": "function", "path": "docforge.cli.mcp_utils.discover_module_paths", "signature": "", - "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." + "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: Top-level package name to discover modules from.\n project_root: Root directory used to resolve module paths. If not\n provided, the current working directory is used.\n\nReturns:\n A sorted list of unique dotted module import paths.\n\nRaises:\n FileNotFoundError: If the specified package directory does not exist." }, "MCPRenderer": { "name": "MCPRenderer", "kind": "class", "path": "docforge.cli.mcp_utils.MCPRenderer", "signature": "", - "docstring": "Renderer that emits MCP-native JSON resources from docforge models.", + "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).", "members": { "name": { "name": "name", @@ -467,7 +474,7 @@ "kind": "function", "path": "docforge.cli.mcp_utils.MCPRenderer.generate_sources", "signature": "", - "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." + "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: Documentation project model to render.\n out_dir: Directory where MCP resources will be written." } } }, @@ -476,7 +483,7 @@ "kind": "class", "path": "docforge.cli.mcp_utils.MCPServer", "signature": "", - "docstring": "MCP server for serving a pre-built MCP documentation bundle.", + "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.", "members": { "mcp_root": { "name": "mcp_root", @@ -497,7 +504,7 @@ "kind": "function", "path": "docforge.cli.mcp_utils.MCPServer.run", "signature": "", - "docstring": "Start the MCP server.\n\nArgs:\n transport: MCP transport (default: streamable-http)" + "docstring": "Start the MCP server.\n\nArgs:\n transport: Transport mechanism used by the MCP server. Supported\n options include ``stdio``, ``sse``, and ``streamable-http``." } } }, @@ -505,15 +512,15 @@ "name": "generate_resources", "kind": "function", "path": "docforge.cli.mcp_utils.generate_resources", - "signature": "", - "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." + "signature": "", + "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: Python module import path used as the entry point for\n documentation generation.\n project_name: Optional override for the project name used in\n generated documentation metadata.\n out_dir: Directory where MCP resources (index.json, nav.json,\n and module data) will be written." }, "serve": { "name": "serve", "kind": "function", "path": "docforge.cli.mcp_utils.serve", - "signature": "", - "docstring": "Serve MCP documentation from a pre-built bundle.\n\nArgs:\n module: The dotted path of the primary module to serve.\n mcp_root: Path to the directory containing index.json, nav.json, and modules/." + "signature": "", + "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: Python module import path used to identify the served\n documentation instance.\n mcp_root: Path to the directory containing the MCP documentation\n bundle (index.json, nav.json, and modules/).\n\nRaises:\n click.ClickException: If the MCP documentation bundle is missing\n required files or directories." } } }, @@ -557,21 +564,21 @@ "kind": "class", "path": "docforge.cli.mkdocs_utils.GriffeLoader", "signature": "", - "docstring": "Loads Python modules and extracts documentation using the Griffe introspection engine.", + "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.", "members": { "load_project": { "name": "load_project", "kind": "function", "path": "docforge.cli.mkdocs_utils.GriffeLoader.load_project", "signature": "", - "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." + "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 of dotted module import paths to load.\n project_name: Optional override for the project name. Defaults\n to the top-level name of the first module.\n skip_import_errors: If True, modules that fail to load will be\n skipped instead of raising an error.\n\nReturns:\n A populated ``Project`` instance containing the loaded modules.\n\nRaises:\n ValueError: If no module paths are provided.\n ImportError: If a module fails to load and\n ``skip_import_errors`` is False." }, "load_module": { "name": "load_module", "kind": "function", "path": "docforge.cli.mkdocs_utils.GriffeLoader.load_module", "signature": "", - "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." + "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: Dotted import path of the module.\n\nReturns:\n A populated ``Module`` instance." } } }, @@ -580,14 +587,14 @@ "kind": "function", "path": "docforge.cli.mkdocs_utils.discover_module_paths", "signature": "", - "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." + "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: Top-level package name to discover modules from.\n project_root: Root directory used to resolve module paths. If not\n provided, the current working directory is used.\n\nReturns:\n A sorted list of unique dotted module import paths.\n\nRaises:\n FileNotFoundError: If the specified package directory does not exist." }, "MkDocsRenderer": { "name": "MkDocsRenderer", "kind": "class", "path": "docforge.cli.mkdocs_utils.MkDocsRenderer", "signature": "", - "docstring": "Renderer that generates Markdown source files formatted for the MkDocs\n'mkdocstrings' plugin.", + "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", @@ -601,7 +608,14 @@ "kind": "function", "path": "docforge.cli.mkdocs_utils.MkDocsRenderer.generate_sources", "signature": "", - "docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project: The project models to render.\n out_dir: Target directory for documentation files.\n module_is_source: Module is the source folder and to be treated as the root folder." + "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 model containing modules to document.\n out_dir: Directory where generated Markdown files will be written.\n module_is_source: If True, treat the specified module as the\n documentation root rather than nesting it inside a folder." + }, + "generate_readme": { + "name": "generate_readme", + "kind": "function", + "path": "docforge.cli.mkdocs_utils.MkDocsRenderer.generate_readme", + "signature": "", + "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\n project root directory.\n- If False, README generation is currently not implemented.\n\nArgs:\n project: Project model containing documentation metadata.\n docs_dir: Directory containing generated documentation sources.\n module_is_source: Whether the module is treated as the project\n source root." } } }, @@ -610,28 +624,28 @@ "kind": "function", "path": "docforge.cli.mkdocs_utils.load_nav_spec", "signature": "", - "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." + "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." }, "resolve_nav": { "name": "resolve_nav", "kind": "function", "path": "docforge.cli.mkdocs_utils.resolve_nav", "signature": "", - "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." + "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." }, "MkDocsNavEmitter": { "name": "MkDocsNavEmitter", "kind": "class", "path": "docforge.cli.mkdocs_utils.MkDocsNavEmitter", "signature": "", - "docstring": "Emitter responsible for transforming a ResolvedNav into an MkDocs-compatible\nnavigation structure.", + "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.", "members": { "emit": { "name": "emit", "kind": "function", "path": "docforge.cli.mkdocs_utils.MkDocsNavEmitter.emit", "signature": "", - "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." + "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." } } }, @@ -639,29 +653,29 @@ "name": "generate_sources", "kind": "function", "path": "docforge.cli.mkdocs_utils.generate_sources", - "signature": "", - "docstring": "Generate Markdown source files for the specified module.\n\nArgs:\n module: The dotted path of the primary module to document.\n project_name: Optional override for the project name.\n docs_dir: Directory where the generated Markdown files will be written.\n module_is_source: Module is the source folder and to be treated as the root folder." + "signature": "", + "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: Python module import path used as the entry point for\n documentation generation.\n docs_dir: Directory where the generated Markdown files will be written.\n project_name: Optional override for the project name used in\n documentation metadata.\n module_is_source: If True, treat the specified module directory as\n the project root rather than a nested module." }, "generate_config": { "name": "generate_config", "kind": "function", "path": "docforge.cli.mkdocs_utils.generate_config", - "signature": "", - "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." + "signature": "", + "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: Directory containing generated documentation Markdown files.\n nav_file: Path to the ``docforge.nav.yml`` navigation specification.\n template: Optional path to a custom MkDocs configuration template.\n If not provided, a built-in template will be used.\n out: Destination path where the generated ``mkdocs.yml`` file\n will be written.\n site_name: Display name for the generated documentation site.\n\nRaises:\n click.FileError: If the navigation specification or template\n file cannot be found." }, "build": { "name": "build", "kind": "function", "path": "docforge.cli.mkdocs_utils.build", - "signature": "", - "docstring": "Build the documentation site using MkDocs.\n\nArgs:\n mkdocs_yml: Path to the mkdocs.yml configuration file." + "signature": "", + "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 to the ``mkdocs.yml`` configuration file.\n\nRaises:\n click.ClickException: If the configuration file does not exist." }, "serve": { "name": "serve", "kind": "function", "path": "docforge.cli.mkdocs_utils.serve", - "signature": "", - "docstring": "Serve the documentation site with live-reload using MkDocs.\n\nArgs:\n mkdocs_yml: Path to the mkdocs.yml configuration file." + "signature": "", + "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 to the ``mkdocs.yml`` configuration file.\n\nRaises:\n click.ClickException: If the configuration file does not exist." } } } diff --git a/mcp_docs/modules/docforge.cli.main.json b/mcp_docs/modules/docforge.cli.main.json index c11662a..35e06dd 100644 --- a/mcp_docs/modules/docforge.cli.main.json +++ b/mcp_docs/modules/docforge.cli.main.json @@ -2,7 +2,7 @@ "module": "docforge.cli.main", "content": { "path": "docforge.cli.main", - "docstring": "Main entry point for the doc-forge CLI. This module delegates all command\nexecution to docforge.cli.commands.", + "docstring": "Command-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``.", "objects": { "cli": { "name": "cli", @@ -15,8 +15,8 @@ "name": "main", "kind": "function", "path": "docforge.cli.main.main", - "signature": "", - "docstring": "CLI Entry point. Boots the click application." + "signature": "", + "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." } } } diff --git a/mcp_docs/modules/docforge.cli.mcp_utils.json b/mcp_docs/modules/docforge.cli.mcp_utils.json index 92c0682..a222082 100644 --- a/mcp_docs/modules/docforge.cli.mcp_utils.json +++ b/mcp_docs/modules/docforge.cli.mcp_utils.json @@ -23,21 +23,21 @@ "kind": "class", "path": "docforge.cli.mcp_utils.GriffeLoader", "signature": "", - "docstring": "Loads Python modules and extracts documentation using the Griffe introspection engine.", + "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.", "members": { "load_project": { "name": "load_project", "kind": "function", "path": "docforge.cli.mcp_utils.GriffeLoader.load_project", "signature": "", - "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." + "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 of dotted module import paths to load.\n project_name: Optional override for the project name. Defaults\n to the top-level name of the first module.\n skip_import_errors: If True, modules that fail to load will be\n skipped instead of raising an error.\n\nReturns:\n A populated ``Project`` instance containing the loaded modules.\n\nRaises:\n ValueError: If no module paths are provided.\n ImportError: If a module fails to load and\n ``skip_import_errors`` is False." }, "load_module": { "name": "load_module", "kind": "function", "path": "docforge.cli.mcp_utils.GriffeLoader.load_module", "signature": "", - "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." + "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: Dotted import path of the module.\n\nReturns:\n A populated ``Module`` instance." } } }, @@ -46,14 +46,14 @@ "kind": "function", "path": "docforge.cli.mcp_utils.discover_module_paths", "signature": "", - "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." + "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: Top-level package name to discover modules from.\n project_root: Root directory used to resolve module paths. If not\n provided, the current working directory is used.\n\nReturns:\n A sorted list of unique dotted module import paths.\n\nRaises:\n FileNotFoundError: If the specified package directory does not exist." }, "MCPRenderer": { "name": "MCPRenderer", "kind": "class", "path": "docforge.cli.mcp_utils.MCPRenderer", "signature": "", - "docstring": "Renderer that emits MCP-native JSON resources from docforge models.", + "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).", "members": { "name": { "name": "name", @@ -67,7 +67,7 @@ "kind": "function", "path": "docforge.cli.mcp_utils.MCPRenderer.generate_sources", "signature": "", - "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." + "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: Documentation project model to render.\n out_dir: Directory where MCP resources will be written." } } }, @@ -76,7 +76,7 @@ "kind": "class", "path": "docforge.cli.mcp_utils.MCPServer", "signature": "", - "docstring": "MCP server for serving a pre-built MCP documentation bundle.", + "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.", "members": { "mcp_root": { "name": "mcp_root", @@ -97,7 +97,7 @@ "kind": "function", "path": "docforge.cli.mcp_utils.MCPServer.run", "signature": "", - "docstring": "Start the MCP server.\n\nArgs:\n transport: MCP transport (default: streamable-http)" + "docstring": "Start the MCP server.\n\nArgs:\n transport: Transport mechanism used by the MCP server. Supported\n options include ``stdio``, ``sse``, and ``streamable-http``." } } }, @@ -105,15 +105,15 @@ "name": "generate_resources", "kind": "function", "path": "docforge.cli.mcp_utils.generate_resources", - "signature": "", - "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." + "signature": "", + "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: Python module import path used as the entry point for\n documentation generation.\n project_name: Optional override for the project name used in\n generated documentation metadata.\n out_dir: Directory where MCP resources (index.json, nav.json,\n and module data) will be written." }, "serve": { "name": "serve", "kind": "function", "path": "docforge.cli.mcp_utils.serve", - "signature": "", - "docstring": "Serve MCP documentation from a pre-built bundle.\n\nArgs:\n module: The dotted path of the primary module to serve.\n mcp_root: Path to the directory containing index.json, nav.json, and modules/." + "signature": "", + "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: Python module import path used to identify the served\n documentation instance.\n mcp_root: Path to the directory containing the MCP documentation\n bundle (index.json, nav.json, and modules/).\n\nRaises:\n click.ClickException: If the MCP documentation bundle is missing\n required files or directories." } } } diff --git a/mcp_docs/modules/docforge.cli.mkdocs_utils.json b/mcp_docs/modules/docforge.cli.mkdocs_utils.json index 92af3a4..d18f633 100644 --- a/mcp_docs/modules/docforge.cli.mkdocs_utils.json +++ b/mcp_docs/modules/docforge.cli.mkdocs_utils.json @@ -37,21 +37,21 @@ "kind": "class", "path": "docforge.cli.mkdocs_utils.GriffeLoader", "signature": "", - "docstring": "Loads Python modules and extracts documentation using the Griffe introspection engine.", + "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.", "members": { "load_project": { "name": "load_project", "kind": "function", "path": "docforge.cli.mkdocs_utils.GriffeLoader.load_project", "signature": "", - "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." + "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 of dotted module import paths to load.\n project_name: Optional override for the project name. Defaults\n to the top-level name of the first module.\n skip_import_errors: If True, modules that fail to load will be\n skipped instead of raising an error.\n\nReturns:\n A populated ``Project`` instance containing the loaded modules.\n\nRaises:\n ValueError: If no module paths are provided.\n ImportError: If a module fails to load and\n ``skip_import_errors`` is False." }, "load_module": { "name": "load_module", "kind": "function", "path": "docforge.cli.mkdocs_utils.GriffeLoader.load_module", "signature": "", - "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." + "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: Dotted import path of the module.\n\nReturns:\n A populated ``Module`` instance." } } }, @@ -60,14 +60,14 @@ "kind": "function", "path": "docforge.cli.mkdocs_utils.discover_module_paths", "signature": "", - "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." + "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: Top-level package name to discover modules from.\n project_root: Root directory used to resolve module paths. If not\n provided, the current working directory is used.\n\nReturns:\n A sorted list of unique dotted module import paths.\n\nRaises:\n FileNotFoundError: If the specified package directory does not exist." }, "MkDocsRenderer": { "name": "MkDocsRenderer", "kind": "class", "path": "docforge.cli.mkdocs_utils.MkDocsRenderer", "signature": "", - "docstring": "Renderer that generates Markdown source files formatted for the MkDocs\n'mkdocstrings' plugin.", + "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", @@ -81,7 +81,14 @@ "kind": "function", "path": "docforge.cli.mkdocs_utils.MkDocsRenderer.generate_sources", "signature": "", - "docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project: The project models to render.\n out_dir: Target directory for documentation files.\n module_is_source: Module is the source folder and to be treated as the root folder." + "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 model containing modules to document.\n out_dir: Directory where generated Markdown files will be written.\n module_is_source: If True, treat the specified module as the\n documentation root rather than nesting it inside a folder." + }, + "generate_readme": { + "name": "generate_readme", + "kind": "function", + "path": "docforge.cli.mkdocs_utils.MkDocsRenderer.generate_readme", + "signature": "", + "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\n project root directory.\n- If False, README generation is currently not implemented.\n\nArgs:\n project: Project model containing documentation metadata.\n docs_dir: Directory containing generated documentation sources.\n module_is_source: Whether the module is treated as the project\n source root." } } }, @@ -90,28 +97,28 @@ "kind": "function", "path": "docforge.cli.mkdocs_utils.load_nav_spec", "signature": "", - "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." + "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." }, "resolve_nav": { "name": "resolve_nav", "kind": "function", "path": "docforge.cli.mkdocs_utils.resolve_nav", "signature": "", - "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." + "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." }, "MkDocsNavEmitter": { "name": "MkDocsNavEmitter", "kind": "class", "path": "docforge.cli.mkdocs_utils.MkDocsNavEmitter", "signature": "", - "docstring": "Emitter responsible for transforming a ResolvedNav into an MkDocs-compatible\nnavigation structure.", + "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.", "members": { "emit": { "name": "emit", "kind": "function", "path": "docforge.cli.mkdocs_utils.MkDocsNavEmitter.emit", "signature": "", - "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." + "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." } } }, @@ -119,29 +126,29 @@ "name": "generate_sources", "kind": "function", "path": "docforge.cli.mkdocs_utils.generate_sources", - "signature": "", - "docstring": "Generate Markdown source files for the specified module.\n\nArgs:\n module: The dotted path of the primary module to document.\n project_name: Optional override for the project name.\n docs_dir: Directory where the generated Markdown files will be written.\n module_is_source: Module is the source folder and to be treated as the root folder." + "signature": "", + "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: Python module import path used as the entry point for\n documentation generation.\n docs_dir: Directory where the generated Markdown files will be written.\n project_name: Optional override for the project name used in\n documentation metadata.\n module_is_source: If True, treat the specified module directory as\n the project root rather than a nested module." }, "generate_config": { "name": "generate_config", "kind": "function", "path": "docforge.cli.mkdocs_utils.generate_config", - "signature": "", - "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." + "signature": "", + "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: Directory containing generated documentation Markdown files.\n nav_file: Path to the ``docforge.nav.yml`` navigation specification.\n template: Optional path to a custom MkDocs configuration template.\n If not provided, a built-in template will be used.\n out: Destination path where the generated ``mkdocs.yml`` file\n will be written.\n site_name: Display name for the generated documentation site.\n\nRaises:\n click.FileError: If the navigation specification or template\n file cannot be found." }, "build": { "name": "build", "kind": "function", "path": "docforge.cli.mkdocs_utils.build", - "signature": "", - "docstring": "Build the documentation site using MkDocs.\n\nArgs:\n mkdocs_yml: Path to the mkdocs.yml configuration file." + "signature": "", + "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 to the ``mkdocs.yml`` configuration file.\n\nRaises:\n click.ClickException: If the configuration file does not exist." }, "serve": { "name": "serve", "kind": "function", "path": "docforge.cli.mkdocs_utils.serve", - "signature": "", - "docstring": "Serve the documentation site with live-reload using MkDocs.\n\nArgs:\n mkdocs_yml: Path to the mkdocs.yml configuration file." + "signature": "", + "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 to the ``mkdocs.yml`` configuration file.\n\nRaises:\n click.ClickException: If the configuration file does not exist." } } } diff --git a/mcp_docs/modules/docforge.json b/mcp_docs/modules/docforge.json index 17ed506..bfc37df 100644 --- a/mcp_docs/modules/docforge.json +++ b/mcp_docs/modules/docforge.json @@ -2,28 +2,28 @@ "module": "docforge", "content": { "path": "docforge", - "docstring": "Renderer-agnostic Python documentation compiler that converts docstrings into\nstructured documentation for both humans (MkDocs) and machines (MCP / AI agents).\n\n`doc-forge` statically analyzes your source code, builds a semantic model of\nmodules and objects, and renders that model into documentation outputs without\nexecuting your code.\n---\n\n# Core Philosophy\n\n`doc-forge` follows a compiler architecture:\n\n1. **Front-end (Introspection)**\n Static analysis of modules, classes, functions, signatures, and docstrings.\n\n2. **Middle-end (Semantic Model)**\n Renderer-neutral structured representation of your API.\n\n3. **Back-end (Renderers)**\n\n * MkDocs → human documentation\n * MCP JSON → AI-readable documentation\n---\n\n# Docstring Writing Standard\n\nDocstrings are the single source of truth. `doc-forge` does not generate content.\nIt compiles and renders what you write.\n\nDocumentation follows the Python import hierarchy.\n---\n\n# Package docstring (`package/__init__.py`) — Full user guide\n\nThis is the landing page. A developer must be able to install and use the\npackage after reading only this docstring.\n\n## Example:\n\n '''\n Short description of what this package provides.\n\n # Installation\n\n ```bash\n pip install my-package\n ```\n\n # Quick start\n\n ```python\n from my_package.foo import Bar\n\n bar = Bar()\n result = bar.process(\"example\")\n ```\n ---\n\n # Core concepts\n\n ## Bar\n - Primary object exposed by the package.\n\n ## foo module\n - Provides core functionality.\n ---\n\n # Typical workflow\n\n 1. Import public objects\n 2. Initialize objects\n 3. Call methods\n ---\n\n # Public API\n\n foo.Bar\n foo.helper_function\n ---\n '''\n---\n\n# Submodule docstring (`package/foo/__init__.py`) — Subsystem guide\n\nExplains a specific subsystem.\n\n## Example:\n\n '''\n Provides core functionality.\n\n # Usage\n\n ```python\n from my_package.foo import Bar\n\n bar = Bar()\n bar.process(\"example\")\n ```\n ---\n '''\n---\n\n# Class docstring — Object contract\n\nDefines responsibility and behavior.\n\n## Example:\n\n```python\nclass Bar:\n '''\n Performs processing on input data.\n\n Instances may be reused across multiple calls.\n ---\n '''\n```\n\nInclude:\n\n* Responsibility\n* Lifecycle expectations\n* Thread safety (if relevant)\n* Performance characteristics (if relevant)\n---\n\n# Function and method docstrings — API specification\n\n## Example:\n\n```python\ndef process(\n self,\n value1: str,\n value2: str | None = \"default value\",\n value3: str | None = None,\n) -> str:\n '''\n Process an input value.\n ---\n\n Parameters\n ----------\n value1 : str\n required: True\n value to be processed\n Example:\n 'string'\n\n value2 : str\n required: False\n default: \"default value\"\n value to be processed\n Example:\n 'string'\n\n value3 : str\n required: False\n value to be processed\n Example:\n 'string'\n ---\n\n Returns\n -------\n processed value : str\n result after processing value\n ---\n\n Behavior\n --------\n - behaviour 1\n - behaviour 2\n ---\n '''\n```\n---\n\n# Attribute docstrings (optional)\n\n## Example:\n\n```python\nclass Class\n '''\n attribute1 : str\n required: True\n default: \"default value\"\n attribute description\n\n attribute2 : str\n required: False\n attribute description\n\n attribute2 : str\n required: False\n default: \"default value\"\n attribute description\n '''\n\n attribute1: str = \"default value\"\n attribute2: str | None = None\n attribute3: str | None = \"default value\"\n```\n---\n\n# Writing Rules\n\n**Heading hierarchy**\n\nModule docstring\n\n- Examples\n- Usage\n- Core concepts\n- Public API\n\nClass docstring\n\n- Attributes\n- Execution contract\n- Lifecycle\n- Thread safety\n- Notes\n\nMethod docstring\n\n- Parameters\n- Returns\n- Raises\n- Yields\n- Behavior\n\n**Required**\n\n* Use Markdown headings\n* Use Markdown line separator `---`\n* Line separator should be followed by a blank line\n* Provide real import examples\n* Document all public APIs\n* Keep descriptions precise and factual\n\n**Avoid**\n\n* Plain-text separators like `====`\n* Duplicate external documentation\n* Informal or conversational language\n---\n\n# How doc-forge uses these docstrings\n\n## Build MkDocs site:\n\n```bash\ndoc-forge build --mkdocs --module my_package\n```\n\n## Build MCP documentation:\n\n```bash\ndoc-forge build --mcp --module my_package\n```\n\nBoth outputs are generated directly from docstrings.\n---", + "docstring": "Renderer-agnostic Python documentation compiler that converts Python docstrings\ninto structured documentation for both humans (MkDocs) and machines (MCP / AI agents).\n\n`doc-forge` statically analyzes source code, builds a semantic model of modules,\nclasses, functions, and attributes, and renders that model into documentation\noutputs without executing user code.\n\n---\n\n## Installation\n\nInstall using pip:\n\n pip install doc-forge\n\n---\n\n## Quick start\n\nGenerate a MkDocs site from a Python package:\n\n doc-forge build --mkdocs --module my_package\n\nGenerate MCP JSON documentation:\n\n doc-forge build --mcp --module my_package\n\nServe documentation locally:\n\n doc-forge serve --mkdocs --module my_package\n\n---\n\n## Core concepts\n\n**Loader**\n\nExtracts symbols, signatures, and docstrings using static analysis.\n\n**Semantic model**\n\nStructured, renderer-agnostic representation of the API.\n\n**Renderer**\n\nConverts the semantic model into output formats such as MkDocs or MCP JSON.\n\n**Symbol**\n\nAny documentable object:\n\n - module\n - class\n - function\n - method\n - property\n - attribute\n\n---\n\n## Architecture\n\n`doc-forge` follows a compiler architecture:\n\nFront-end:\n\n Static analysis of modules, classes, functions, type hints, and docstrings.\n\nMiddle-end:\n\n Builds a semantic model describing symbols and relationships.\n\nBack-end:\n\n Renders documentation using interchangeable renderers.\n\nThis architecture ensures deterministic documentation generation.\n\n---\n\n## Rendering pipeline\n\nTypical flow:\n\n Python package\n ↓\n Loader (static analysis)\n ↓\n Semantic model\n ↓\n Renderer\n ↓\n MkDocs site or MCP JSON\n\n---\n\n## CLI usage\n\nBuild MkDocs documentation:\n\n doc-forge build --mkdocs --module my_package\n\nBuild MCP documentation:\n\n doc-forge build --mcp --module my_package\n\nServe MkDocs locally:\n\n doc-forge serve --module my_package\n\n---\n\n## Public API\n\nLoaders:\n\n GriffeLoader\n discover_module_paths\n\nRenderers:\n\n MkDocsRenderer\n MCPRenderer\n\nCLI:\n\n main\n\nModels:\n\n models\n\n---\n\n# Google-Styled Doc-Forge Convention (GSDFC)\n\nGSDFC defines how docstrings must be written so they render correctly in MkDocs and remain machine-parsable by doc-forge and AI tooling.\n\n- Docstrings are the single source of truth.\n- doc-forge compiles docstrings but does not generate documentation content.\n- Documentation follows the Python import hierarchy.\n- Every public symbol should have a complete and accurate docstring.\n\n---\n\n## General rules\n\n- Use **Markdown headings** at package and module level.\n- Use **Google-style structured sections** at class, function, and method level.\n- Indent section contents using four spaces.\n- Use type hints in signatures instead of duplicating types in prose.\n- Write summaries in imperative form.\n- Sections are separated by ```---```\n\n---\n\n## Package docstrings\n\n- Package docstrings act as the documentation home page.\n\nRecommended sections:\n\n ## Summary\n ## Installation\n ## Quick start\n ## Core concepts\n ## Architecture\n ## Rendering pipeline\n ## CLI usage\n ## Public API\n ## Examples\n ## Notes\n\nExample:\n Package Doc String:\n\n '''\n Foo-bar processing framework.\n\n Provides tools for defining Foo objects and executing Bar pipelines.\n\n ---\n\n # Installation\n\n pip install foo-bar\n\n ---\n\n # Quick start\n\n from foobar import Foo, BarEngine\n\n foo = Foo(\"example\")\n engine = BarEngine([foo])\n\n result = engine.run()\n\n ---\n\n # Public API\n\n Foo\n Bar\n BarEngine\n\n ---\n '''\n\n---\n\n## Module docstrings\n\n- Module docstrings describe a subsystem.\n\nRecommended sections:\n\n ## Summary\n ## Examples\n ## Notes\n ## Public API\n\nExample:\n Module Doc String:\n\n '''\n Foo execution subsystem.\n\n Provides utilities for executing Foo objects through Bar stages.\n\n ---\n\n Example:\n\n from foobar.engine import BarEngine\n from foobar.foo import Foo\n\n foo = Foo(\"example\")\n\n engine = BarEngine([foo])\n engine.run()\n\n ---\n '''\n\n---\n\n## Class docstrings\n\n- Class docstrings define object responsibility, lifecycle, and attributes.\n\nRecommended sections:\n\n Attributes:\n Notes:\n Example:\n Raises:\n\nExample:\n Simple Foo:\n\n class Foo:\n '''\n Represents a unit of work.\n\n Attributes:\n name (str):\n Identifier of the foo instance.\n\n value (int):\n Numeric value associated with foo.\n\n Notes:\n Guarantees:\n\n - instances are immutable after creation\n\n Lifecycle:\n\n - create instance\n - pass to processing engine\n\n Example:\n Create and inspect a Foo:\n\n foo = Foo(\"example\", value=42)\n print(foo.name)\n '''\n\n Complex Bar:\n\n class BarEngine:\n '''\n Executes Foo objects through Bar stages.\n\n Attributes:\n foos (tuple[Foo, ...]):\n Foo instances managed by the engine.\n\n Notes:\n Guarantees:\n\n - deterministic execution order\n\n Example:\n Run engine:\n\n foo1 = Foo(\"a\")\n foo2 = Foo(\"b\")\n\n engine = BarEngine([foo1, foo2])\n engine.run()\n '''\n\n---\n\n## Function and method docstrings\n\n- Function docstrings define API contracts.\n\nRecommended sections:\n\n Args:\n Returns:\n Raises:\n Yields:\n Notes:\n Example:\n\nExample:\n Simple process method:\n\n def process(foo: Foo, multiplier: int) -> int:\n '''\n Process a Foo instance.\n\n Args:\n foo (Foo):\n Foo instance to process.\n\n multiplier (int):\n Value used to scale foo.\n\n Returns:\n int:\n Processed result.\n\n Raises:\n ValueError:\n If multiplier is negative.\n\n Notes:\n Guarantees:\n\n - foo is not modified\n\n Example:\n Process foo:\n\n foo = Foo(\"example\", value=10)\n\n result = process(foo, multiplier=2)\n print(result)\n '''\n\n Multiple Examples:\n\n def combine(foo_a: Foo, foo_b: Foo) -> Foo:\n '''\n Combine two Foo instances.\n\n Args:\n foo_a (Foo):\n First foo.\n\n foo_b (Foo):\n Second foo.\n\n Returns:\n Foo:\n Combined foo.\n\n Example:\n Basic usage:\n\n foo1 = Foo(\"a\")\n foo2 = Foo(\"b\")\n\n combined = combine(foo1, foo2)\n\n Pipeline usage:\n\n engine = BarEngine([foo1, foo2])\n engine.run()\n '''\n\n---\n\n## Property docstrings\n\n- Properties must document return values.\n\nExample:\n Property Doc String:\n\n @property\n def foos(self) -> tuple[Foo, ...]:\n '''\n Return contained Foo instances.\n\n Returns:\n tuple[Foo, ...]:\n Stored foo objects.\n\n Example:\n container = FooContainer()\n\n foos = container.foos\n '''\n\n---\n\n## Attribute documentation\n\n- Document attributes in class docstrings using Attributes:.\n\nExample:\n Attribute Doc String:\n\n '''\n Represents a processing stage.\n\n Attributes:\n id (str):\n Unique identifier.\n\n enabled (bool):\n Whether the stage is active.\n '''\n\n---\n\n## Notes subsection grouping\n\n- Group related information using labeled subsections.\n\nExample:\n Notes Example:\n\n Notes:\n **Guarantees:**\n\n - deterministic behavior\n\n **Lifecycle:**\n\n - created during initialization\n - reused across executions\n\n **Thread safety:**\n\n - safe for concurrent reads\n\n---\n\n## Example formatting\n\n- Use indentation for examples.\n\nExample:\n Single example:\n\n Example:\n\n foo = Foo(\"example\")\n process(foo, multiplier=2)\n\n Multiple examples:\n\n Example:\n Create foo:\n\n foo = Foo(\"example\")\n\n Run engine:\n\n engine = BarEngine([foo])\n engine.run()\n\nAvoid fenced code blocks inside structured sections.\n\n---\n\n## Separator rules\n\nUse horizontal separators only at docstring root level to separate sections:\n\n ---\n\nAllowed locations:\n\n- package docstrings\n- module docstrings\n- major documentation sections\n\nDo not use separators inside code sections.\n\n---\n\n## Parsing guarantees\n\nGSDFC ensures doc-forge can deterministically extract:\n\n- symbol kind (module, class, function, property, attribute)\n- symbol name\n- parameters\n- return values\n- attributes\n- examples\n- structured Notes subsections\n\nThis enables:\n\n- reliable MkDocs rendering\n- deterministic MCP export\n- accurate AI semantic interpretation\n\n---\n\nNotes:\n - doc-forge never executes analyzed modules.\n - Documentation is generated entirely through static analysis.", "objects": { "GriffeLoader": { "name": "GriffeLoader", "kind": "class", "path": "docforge.GriffeLoader", "signature": "", - "docstring": "Loads Python modules and extracts documentation using the Griffe introspection engine.", + "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.", "members": { "load_project": { "name": "load_project", "kind": "function", "path": "docforge.GriffeLoader.load_project", "signature": "", - "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." + "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 of dotted module import paths to load.\n project_name: Optional override for the project name. Defaults\n to the top-level name of the first module.\n skip_import_errors: If True, modules that fail to load will be\n skipped instead of raising an error.\n\nReturns:\n A populated ``Project`` instance containing the loaded modules.\n\nRaises:\n ValueError: If no module paths are provided.\n ImportError: If a module fails to load and\n ``skip_import_errors`` is False." }, "load_module": { "name": "load_module", "kind": "function", "path": "docforge.GriffeLoader.load_module", "signature": "", - "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." + "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: Dotted import path of the module.\n\nReturns:\n A populated ``Module`` instance." } } }, @@ -32,14 +32,14 @@ "kind": "function", "path": "docforge.discover_module_paths", "signature": "", - "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." + "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: Top-level package name to discover modules from.\n project_root: Root directory used to resolve module paths. If not\n provided, the current working directory is used.\n\nReturns:\n A sorted list of unique dotted module import paths.\n\nRaises:\n FileNotFoundError: If the specified package directory does not exist." }, "MkDocsRenderer": { "name": "MkDocsRenderer", "kind": "class", "path": "docforge.MkDocsRenderer", "signature": "", - "docstring": "Renderer that generates Markdown source files formatted for the MkDocs\n'mkdocstrings' plugin.", + "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", @@ -53,7 +53,14 @@ "kind": "function", "path": "docforge.MkDocsRenderer.generate_sources", "signature": "", - "docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project: The project models to render.\n out_dir: Target directory for documentation files.\n module_is_source: Module is the source folder and to be treated as the root folder." + "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 model containing modules to document.\n out_dir: Directory where generated Markdown files will be written.\n module_is_source: If True, treat the specified module as the\n documentation root rather than nesting it inside a folder." + }, + "generate_readme": { + "name": "generate_readme", + "kind": "function", + "path": "docforge.MkDocsRenderer.generate_readme", + "signature": "", + "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\n project root directory.\n- If False, README generation is currently not implemented.\n\nArgs:\n project: Project model containing documentation metadata.\n docs_dir: Directory containing generated documentation sources.\n module_is_source: Whether the module is treated as the project\n source root." } } }, @@ -62,7 +69,7 @@ "kind": "class", "path": "docforge.MCPRenderer", "signature": "", - "docstring": "Renderer that emits MCP-native JSON resources from docforge models.", + "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).", "members": { "name": { "name": "name", @@ -76,7 +83,7 @@ "kind": "function", "path": "docforge.MCPRenderer.generate_sources", "signature": "", - "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." + "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: Documentation project model to render.\n out_dir: Directory where MCP resources will be written." } } }, @@ -85,7 +92,7 @@ "kind": "module", "path": "docforge.main", "signature": "", - "docstring": "Main entry point for the doc-forge CLI. This module delegates all command\nexecution to docforge.cli.commands.", + "docstring": "Command-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``.", "members": { "cli": { "name": "cli", @@ -99,7 +106,7 @@ "kind": "function", "path": "docforge.main.main", "signature": "", - "docstring": "CLI Entry point. Boots the click application." + "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." } } }, @@ -108,14 +115,14 @@ "kind": "module", "path": "docforge.cli", "signature": null, - "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.", + "docstring": "Command 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\nTypical usage\n-------------\n\nThe CLI is normally invoked through the installed command:\n\n doc-forge [options]\n\nProgrammatic invocation is also possible:\n\n from docforge.cli import main\n main()\n\n---", "members": { "main": { "name": "main", "kind": "module", "path": "docforge.cli.main", "signature": null, - "docstring": "Main entry point for the doc-forge CLI. This module delegates all command\nexecution to docforge.cli.commands.", + "docstring": "Command-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``.", "members": { "cli": { "name": "cli", @@ -128,8 +135,8 @@ "name": "main", "kind": "function", "path": "docforge.cli.main.main", - "signature": "", - "docstring": "CLI Entry point. Boots the click application." + "signature": "", + "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." } } }, @@ -173,21 +180,21 @@ "kind": "class", "path": "docforge.cli.commands.GriffeLoader", "signature": "", - "docstring": "Loads Python modules and extracts documentation using the Griffe introspection engine.", + "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.", "members": { "load_project": { "name": "load_project", "kind": "function", "path": "docforge.cli.commands.GriffeLoader.load_project", "signature": "", - "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." + "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 of dotted module import paths to load.\n project_name: Optional override for the project name. Defaults\n to the top-level name of the first module.\n skip_import_errors: If True, modules that fail to load will be\n skipped instead of raising an error.\n\nReturns:\n A populated ``Project`` instance containing the loaded modules.\n\nRaises:\n ValueError: If no module paths are provided.\n ImportError: If a module fails to load and\n ``skip_import_errors`` is False." }, "load_module": { "name": "load_module", "kind": "function", "path": "docforge.cli.commands.GriffeLoader.load_module", "signature": "", - "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." + "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: Dotted import path of the module.\n\nReturns:\n A populated ``Module`` instance." } } }, @@ -231,21 +238,21 @@ "kind": "class", "path": "docforge.cli.commands.mkdocs_utils.GriffeLoader", "signature": "", - "docstring": "Loads Python modules and extracts documentation using the Griffe introspection engine.", + "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.", "members": { "load_project": { "name": "load_project", "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.GriffeLoader.load_project", "signature": "", - "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." + "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 of dotted module import paths to load.\n project_name: Optional override for the project name. Defaults\n to the top-level name of the first module.\n skip_import_errors: If True, modules that fail to load will be\n skipped instead of raising an error.\n\nReturns:\n A populated ``Project`` instance containing the loaded modules.\n\nRaises:\n ValueError: If no module paths are provided.\n ImportError: If a module fails to load and\n ``skip_import_errors`` is False." }, "load_module": { "name": "load_module", "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.GriffeLoader.load_module", "signature": "", - "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." + "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: Dotted import path of the module.\n\nReturns:\n A populated ``Module`` instance." } } }, @@ -254,14 +261,14 @@ "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.discover_module_paths", "signature": "", - "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." + "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: Top-level package name to discover modules from.\n project_root: Root directory used to resolve module paths. If not\n provided, the current working directory is used.\n\nReturns:\n A sorted list of unique dotted module import paths.\n\nRaises:\n FileNotFoundError: If the specified package directory does not exist." }, "MkDocsRenderer": { "name": "MkDocsRenderer", "kind": "class", "path": "docforge.cli.commands.mkdocs_utils.MkDocsRenderer", "signature": "", - "docstring": "Renderer that generates Markdown source files formatted for the MkDocs\n'mkdocstrings' plugin.", + "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", @@ -275,7 +282,14 @@ "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.MkDocsRenderer.generate_sources", "signature": "", - "docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project: The project models to render.\n out_dir: Target directory for documentation files.\n module_is_source: Module is the source folder and to be treated as the root folder." + "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 model containing modules to document.\n out_dir: Directory where generated Markdown files will be written.\n module_is_source: If True, treat the specified module as the\n documentation root rather than nesting it inside a folder." + }, + "generate_readme": { + "name": "generate_readme", + "kind": "function", + "path": "docforge.cli.commands.mkdocs_utils.MkDocsRenderer.generate_readme", + "signature": "", + "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\n project root directory.\n- If False, README generation is currently not implemented.\n\nArgs:\n project: Project model containing documentation metadata.\n docs_dir: Directory containing generated documentation sources.\n module_is_source: Whether the module is treated as the project\n source root." } } }, @@ -284,28 +298,28 @@ "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.load_nav_spec", "signature": "", - "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." + "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." }, "resolve_nav": { "name": "resolve_nav", "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.resolve_nav", "signature": "", - "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." + "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." }, "MkDocsNavEmitter": { "name": "MkDocsNavEmitter", "kind": "class", "path": "docforge.cli.commands.mkdocs_utils.MkDocsNavEmitter", "signature": "", - "docstring": "Emitter responsible for transforming a ResolvedNav into an MkDocs-compatible\nnavigation structure.", + "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.", "members": { "emit": { "name": "emit", "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.MkDocsNavEmitter.emit", "signature": "", - "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." + "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." } } }, @@ -314,28 +328,28 @@ "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.generate_sources", "signature": "", - "docstring": "Generate Markdown source files for the specified module.\n\nArgs:\n module: The dotted path of the primary module to document.\n project_name: Optional override for the project name.\n docs_dir: Directory where the generated Markdown files will be written.\n module_is_source: Module is the source folder and to be treated as the root folder." + "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: Python module import path used as the entry point for\n documentation generation.\n docs_dir: Directory where the generated Markdown files will be written.\n project_name: Optional override for the project name used in\n documentation metadata.\n module_is_source: If True, treat the specified module directory as\n the project root rather than a nested module." }, "generate_config": { "name": "generate_config", "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.generate_config", "signature": "", - "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." + "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: Directory containing generated documentation Markdown files.\n nav_file: Path to the ``docforge.nav.yml`` navigation specification.\n template: Optional path to a custom MkDocs configuration template.\n If not provided, a built-in template will be used.\n out: Destination path where the generated ``mkdocs.yml`` file\n will be written.\n site_name: Display name for the generated documentation site.\n\nRaises:\n click.FileError: If the navigation specification or template\n file cannot be found." }, "build": { "name": "build", "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.build", "signature": "", - "docstring": "Build the documentation site using MkDocs.\n\nArgs:\n mkdocs_yml: Path to the mkdocs.yml configuration file." + "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 to the ``mkdocs.yml`` configuration file.\n\nRaises:\n click.ClickException: If the configuration file does not exist." }, "serve": { "name": "serve", "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.serve", "signature": "", - "docstring": "Serve the documentation site with live-reload using MkDocs.\n\nArgs:\n mkdocs_yml: Path to the mkdocs.yml configuration file." + "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 to the ``mkdocs.yml`` configuration file.\n\nRaises:\n click.ClickException: If the configuration file does not exist." } } }, @@ -365,21 +379,21 @@ "kind": "class", "path": "docforge.cli.commands.mcp_utils.GriffeLoader", "signature": "", - "docstring": "Loads Python modules and extracts documentation using the Griffe introspection engine.", + "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.", "members": { "load_project": { "name": "load_project", "kind": "function", "path": "docforge.cli.commands.mcp_utils.GriffeLoader.load_project", "signature": "", - "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." + "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 of dotted module import paths to load.\n project_name: Optional override for the project name. Defaults\n to the top-level name of the first module.\n skip_import_errors: If True, modules that fail to load will be\n skipped instead of raising an error.\n\nReturns:\n A populated ``Project`` instance containing the loaded modules.\n\nRaises:\n ValueError: If no module paths are provided.\n ImportError: If a module fails to load and\n ``skip_import_errors`` is False." }, "load_module": { "name": "load_module", "kind": "function", "path": "docforge.cli.commands.mcp_utils.GriffeLoader.load_module", "signature": "", - "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." + "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: Dotted import path of the module.\n\nReturns:\n A populated ``Module`` instance." } } }, @@ -388,14 +402,14 @@ "kind": "function", "path": "docforge.cli.commands.mcp_utils.discover_module_paths", "signature": "", - "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." + "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: Top-level package name to discover modules from.\n project_root: Root directory used to resolve module paths. If not\n provided, the current working directory is used.\n\nReturns:\n A sorted list of unique dotted module import paths.\n\nRaises:\n FileNotFoundError: If the specified package directory does not exist." }, "MCPRenderer": { "name": "MCPRenderer", "kind": "class", "path": "docforge.cli.commands.mcp_utils.MCPRenderer", "signature": "", - "docstring": "Renderer that emits MCP-native JSON resources from docforge models.", + "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).", "members": { "name": { "name": "name", @@ -409,7 +423,7 @@ "kind": "function", "path": "docforge.cli.commands.mcp_utils.MCPRenderer.generate_sources", "signature": "", - "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." + "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: Documentation project model to render.\n out_dir: Directory where MCP resources will be written." } } }, @@ -418,7 +432,7 @@ "kind": "class", "path": "docforge.cli.commands.mcp_utils.MCPServer", "signature": "", - "docstring": "MCP server for serving a pre-built MCP documentation bundle.", + "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.", "members": { "mcp_root": { "name": "mcp_root", @@ -439,7 +453,7 @@ "kind": "function", "path": "docforge.cli.commands.mcp_utils.MCPServer.run", "signature": "", - "docstring": "Start the MCP server.\n\nArgs:\n transport: MCP transport (default: streamable-http)" + "docstring": "Start the MCP server.\n\nArgs:\n transport: Transport mechanism used by the MCP server. Supported\n options include ``stdio``, ``sse``, and ``streamable-http``." } } }, @@ -448,14 +462,14 @@ "kind": "function", "path": "docforge.cli.commands.mcp_utils.generate_resources", "signature": "", - "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." + "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: Python module import path used as the entry point for\n documentation generation.\n project_name: Optional override for the project name used in\n generated documentation metadata.\n out_dir: Directory where MCP resources (index.json, nav.json,\n and module data) will be written." }, "serve": { "name": "serve", "kind": "function", "path": "docforge.cli.commands.mcp_utils.serve", "signature": "", - "docstring": "Serve MCP documentation from a pre-built bundle.\n\nArgs:\n module: The dotted path of the primary module to serve.\n mcp_root: Path to the directory containing index.json, nav.json, and modules/." + "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: Python module import path used to identify the served\n documentation instance.\n mcp_root: Path to the directory containing the MCP documentation\n bundle (index.json, nav.json, and modules/).\n\nRaises:\n click.ClickException: If the MCP documentation bundle is missing\n required files or directories." } } }, @@ -470,22 +484,22 @@ "name": "build", "kind": "function", "path": "docforge.cli.commands.build", - "signature": "", - "docstring": "Build documentation (MkDocs site or MCP resources).\n\nThis command orchestrates the full build process:\n1. Introspects the code (Griffe)\n2. Renders sources (MkDocs Markdown or MCP JSON)\n3. (MkDocs only) Generates config and runs the final site build.\n\nArgs:\n mcp: Use the MCP documentation builder.\n mkdocs: Use the MkDocs documentation builder.\n module_is_source: Module is the source folder and to be treated as the root folder.\n module: The dotted path of the module to the document.\n project_name: Optional override for the project name.\n site_name: (MkDocs) The site display name. Defaults to module name.\n docs_dir: (MkDocs) Target directory for Markdown sources.\n nav_file: (MkDocs) Path to the docforge.nav.yml specification.\n template: (MkDocs) Optional custom mkdocs.yml template.\n mkdocs_yml: (MkDocs) Target path for the generated mkdocs.yml.\n out_dir: (MCP) Target directory for MCP JSON resources." + "signature": "", + "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: Enable MCP documentation generation.\n mkdocs: Enable MkDocs documentation generation.\n module_is_source: Treat the specified module directory as the\n project root.\n module: Python module import path to document.\n project_name: Optional override for the project name.\n site_name: Display name for the MkDocs site.\n docs_dir: Directory where Markdown documentation sources\n will be generated.\n nav_file: Path to the navigation specification file.\n template: Optional custom MkDocs configuration template.\n mkdocs_yml: Output path for the generated MkDocs configuration.\n out_dir: Output directory for generated MCP resources.\n\nRaises:\n click.UsageError: If required options are missing or conflicting." }, "serve": { "name": "serve", "kind": "function", "path": "docforge.cli.commands.serve", - "signature": "", - "docstring": "Serve documentation (MkDocs or MCP).\n\nArgs:\n mcp: Serve MCP resources via an MCP server.\n mkdocs: Serve the MkDocs site using the built-in development server.\n module: The dotted path of the module to serve.\n mkdocs_yml: (MkDocs) Path to the mkdocs.yml configuration.\n out_dir: (MCP) Path to the mcp_docs/ directory." + "signature": "", + "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: Serve documentation using the MCP server.\n mkdocs: Serve the MkDocs development site.\n module: Python module import path to serve via MCP.\n mkdocs_yml: Path to the MkDocs configuration file.\n out_dir: Root directory containing MCP documentation resources.\n\nRaises:\n click.UsageError: If invalid or conflicting options are provided." }, "tree": { "name": "tree", "kind": "function", "path": "docforge.cli.commands.tree", - "signature": "", - "docstring": "Visualize the project structure in the terminal.\n\nArgs:\n module: The module import path to recursively introspect.\n project_name: Optional override for the project name shown at the root." + "signature": "", + "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: Python module import path to introspect.\n project_name: Optional name to display as the project root." }, "Group": { "name": "Group", @@ -529,21 +543,21 @@ "kind": "class", "path": "docforge.cli.mcp_utils.GriffeLoader", "signature": "", - "docstring": "Loads Python modules and extracts documentation using the Griffe introspection engine.", + "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.", "members": { "load_project": { "name": "load_project", "kind": "function", "path": "docforge.cli.mcp_utils.GriffeLoader.load_project", "signature": "", - "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." + "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 of dotted module import paths to load.\n project_name: Optional override for the project name. Defaults\n to the top-level name of the first module.\n skip_import_errors: If True, modules that fail to load will be\n skipped instead of raising an error.\n\nReturns:\n A populated ``Project`` instance containing the loaded modules.\n\nRaises:\n ValueError: If no module paths are provided.\n ImportError: If a module fails to load and\n ``skip_import_errors`` is False." }, "load_module": { "name": "load_module", "kind": "function", "path": "docforge.cli.mcp_utils.GriffeLoader.load_module", "signature": "", - "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." + "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: Dotted import path of the module.\n\nReturns:\n A populated ``Module`` instance." } } }, @@ -552,14 +566,14 @@ "kind": "function", "path": "docforge.cli.mcp_utils.discover_module_paths", "signature": "", - "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." + "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: Top-level package name to discover modules from.\n project_root: Root directory used to resolve module paths. If not\n provided, the current working directory is used.\n\nReturns:\n A sorted list of unique dotted module import paths.\n\nRaises:\n FileNotFoundError: If the specified package directory does not exist." }, "MCPRenderer": { "name": "MCPRenderer", "kind": "class", "path": "docforge.cli.mcp_utils.MCPRenderer", "signature": "", - "docstring": "Renderer that emits MCP-native JSON resources from docforge models.", + "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).", "members": { "name": { "name": "name", @@ -573,7 +587,7 @@ "kind": "function", "path": "docforge.cli.mcp_utils.MCPRenderer.generate_sources", "signature": "", - "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." + "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: Documentation project model to render.\n out_dir: Directory where MCP resources will be written." } } }, @@ -582,7 +596,7 @@ "kind": "class", "path": "docforge.cli.mcp_utils.MCPServer", "signature": "", - "docstring": "MCP server for serving a pre-built MCP documentation bundle.", + "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.", "members": { "mcp_root": { "name": "mcp_root", @@ -603,7 +617,7 @@ "kind": "function", "path": "docforge.cli.mcp_utils.MCPServer.run", "signature": "", - "docstring": "Start the MCP server.\n\nArgs:\n transport: MCP transport (default: streamable-http)" + "docstring": "Start the MCP server.\n\nArgs:\n transport: Transport mechanism used by the MCP server. Supported\n options include ``stdio``, ``sse``, and ``streamable-http``." } } }, @@ -611,15 +625,15 @@ "name": "generate_resources", "kind": "function", "path": "docforge.cli.mcp_utils.generate_resources", - "signature": "", - "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." + "signature": "", + "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: Python module import path used as the entry point for\n documentation generation.\n project_name: Optional override for the project name used in\n generated documentation metadata.\n out_dir: Directory where MCP resources (index.json, nav.json,\n and module data) will be written." }, "serve": { "name": "serve", "kind": "function", "path": "docforge.cli.mcp_utils.serve", - "signature": "", - "docstring": "Serve MCP documentation from a pre-built bundle.\n\nArgs:\n module: The dotted path of the primary module to serve.\n mcp_root: Path to the directory containing index.json, nav.json, and modules/." + "signature": "", + "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: Python module import path used to identify the served\n documentation instance.\n mcp_root: Path to the directory containing the MCP documentation\n bundle (index.json, nav.json, and modules/).\n\nRaises:\n click.ClickException: If the MCP documentation bundle is missing\n required files or directories." } } }, @@ -663,21 +677,21 @@ "kind": "class", "path": "docforge.cli.mkdocs_utils.GriffeLoader", "signature": "", - "docstring": "Loads Python modules and extracts documentation using the Griffe introspection engine.", + "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.", "members": { "load_project": { "name": "load_project", "kind": "function", "path": "docforge.cli.mkdocs_utils.GriffeLoader.load_project", "signature": "", - "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." + "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 of dotted module import paths to load.\n project_name: Optional override for the project name. Defaults\n to the top-level name of the first module.\n skip_import_errors: If True, modules that fail to load will be\n skipped instead of raising an error.\n\nReturns:\n A populated ``Project`` instance containing the loaded modules.\n\nRaises:\n ValueError: If no module paths are provided.\n ImportError: If a module fails to load and\n ``skip_import_errors`` is False." }, "load_module": { "name": "load_module", "kind": "function", "path": "docforge.cli.mkdocs_utils.GriffeLoader.load_module", "signature": "", - "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." + "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: Dotted import path of the module.\n\nReturns:\n A populated ``Module`` instance." } } }, @@ -686,14 +700,14 @@ "kind": "function", "path": "docforge.cli.mkdocs_utils.discover_module_paths", "signature": "", - "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." + "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: Top-level package name to discover modules from.\n project_root: Root directory used to resolve module paths. If not\n provided, the current working directory is used.\n\nReturns:\n A sorted list of unique dotted module import paths.\n\nRaises:\n FileNotFoundError: If the specified package directory does not exist." }, "MkDocsRenderer": { "name": "MkDocsRenderer", "kind": "class", "path": "docforge.cli.mkdocs_utils.MkDocsRenderer", "signature": "", - "docstring": "Renderer that generates Markdown source files formatted for the MkDocs\n'mkdocstrings' plugin.", + "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", @@ -707,7 +721,14 @@ "kind": "function", "path": "docforge.cli.mkdocs_utils.MkDocsRenderer.generate_sources", "signature": "", - "docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project: The project models to render.\n out_dir: Target directory for documentation files.\n module_is_source: Module is the source folder and to be treated as the root folder." + "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 model containing modules to document.\n out_dir: Directory where generated Markdown files will be written.\n module_is_source: If True, treat the specified module as the\n documentation root rather than nesting it inside a folder." + }, + "generate_readme": { + "name": "generate_readme", + "kind": "function", + "path": "docforge.cli.mkdocs_utils.MkDocsRenderer.generate_readme", + "signature": "", + "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\n project root directory.\n- If False, README generation is currently not implemented.\n\nArgs:\n project: Project model containing documentation metadata.\n docs_dir: Directory containing generated documentation sources.\n module_is_source: Whether the module is treated as the project\n source root." } } }, @@ -716,28 +737,28 @@ "kind": "function", "path": "docforge.cli.mkdocs_utils.load_nav_spec", "signature": "", - "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." + "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." }, "resolve_nav": { "name": "resolve_nav", "kind": "function", "path": "docforge.cli.mkdocs_utils.resolve_nav", "signature": "", - "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." + "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." }, "MkDocsNavEmitter": { "name": "MkDocsNavEmitter", "kind": "class", "path": "docforge.cli.mkdocs_utils.MkDocsNavEmitter", "signature": "", - "docstring": "Emitter responsible for transforming a ResolvedNav into an MkDocs-compatible\nnavigation structure.", + "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.", "members": { "emit": { "name": "emit", "kind": "function", "path": "docforge.cli.mkdocs_utils.MkDocsNavEmitter.emit", "signature": "", - "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." + "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." } } }, @@ -745,29 +766,29 @@ "name": "generate_sources", "kind": "function", "path": "docforge.cli.mkdocs_utils.generate_sources", - "signature": "", - "docstring": "Generate Markdown source files for the specified module.\n\nArgs:\n module: The dotted path of the primary module to document.\n project_name: Optional override for the project name.\n docs_dir: Directory where the generated Markdown files will be written.\n module_is_source: Module is the source folder and to be treated as the root folder." + "signature": "", + "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: Python module import path used as the entry point for\n documentation generation.\n docs_dir: Directory where the generated Markdown files will be written.\n project_name: Optional override for the project name used in\n documentation metadata.\n module_is_source: If True, treat the specified module directory as\n the project root rather than a nested module." }, "generate_config": { "name": "generate_config", "kind": "function", "path": "docforge.cli.mkdocs_utils.generate_config", - "signature": "", - "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." + "signature": "", + "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: Directory containing generated documentation Markdown files.\n nav_file: Path to the ``docforge.nav.yml`` navigation specification.\n template: Optional path to a custom MkDocs configuration template.\n If not provided, a built-in template will be used.\n out: Destination path where the generated ``mkdocs.yml`` file\n will be written.\n site_name: Display name for the generated documentation site.\n\nRaises:\n click.FileError: If the navigation specification or template\n file cannot be found." }, "build": { "name": "build", "kind": "function", "path": "docforge.cli.mkdocs_utils.build", - "signature": "", - "docstring": "Build the documentation site using MkDocs.\n\nArgs:\n mkdocs_yml: Path to the mkdocs.yml configuration file." + "signature": "", + "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 to the ``mkdocs.yml`` configuration file.\n\nRaises:\n click.ClickException: If the configuration file does not exist." }, "serve": { "name": "serve", "kind": "function", "path": "docforge.cli.mkdocs_utils.serve", - "signature": "", - "docstring": "Serve the documentation site with live-reload using MkDocs.\n\nArgs:\n mkdocs_yml: Path to the mkdocs.yml configuration file." + "signature": "", + "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 to the ``mkdocs.yml`` configuration file.\n\nRaises:\n click.ClickException: If the configuration file does not exist." } } } @@ -778,28 +799,28 @@ "kind": "module", "path": "docforge.loaders", "signature": null, - "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.", + "docstring": "Loader 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\nOverview\n--------\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---", "members": { "GriffeLoader": { "name": "GriffeLoader", "kind": "class", "path": "docforge.loaders.GriffeLoader", "signature": "", - "docstring": "Loads Python modules and extracts documentation using the Griffe introspection engine.", + "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.", "members": { "load_project": { "name": "load_project", "kind": "function", "path": "docforge.loaders.GriffeLoader.load_project", "signature": "", - "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." + "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 of dotted module import paths to load.\n project_name: Optional override for the project name. Defaults\n to the top-level name of the first module.\n skip_import_errors: If True, modules that fail to load will be\n skipped instead of raising an error.\n\nReturns:\n A populated ``Project`` instance containing the loaded modules.\n\nRaises:\n ValueError: If no module paths are provided.\n ImportError: If a module fails to load and\n ``skip_import_errors`` is False." }, "load_module": { "name": "load_module", "kind": "function", "path": "docforge.loaders.GriffeLoader.load_module", "signature": "", - "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." + "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: Dotted import path of the module.\n\nReturns:\n A populated ``Module`` instance." } } }, @@ -808,14 +829,14 @@ "kind": "function", "path": "docforge.loaders.discover_module_paths", "signature": "", - "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." + "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: Top-level package name to discover modules from.\n project_root: Root directory used to resolve module paths. If not\n provided, the current working directory is used.\n\nReturns:\n A sorted list of unique dotted module import paths.\n\nRaises:\n FileNotFoundError: If the specified package directory does not exist." }, "griffe_loader": { "name": "griffe_loader", "kind": "module", "path": "docforge.loaders.griffe_loader", "signature": null, - "docstring": "This module provides the GriffeLoader, which uses the 'griffe' library to\nintrospect Python source code and populate the doc-forge Project models.", + "docstring": "Utilities 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.", "members": { "logging": { "name": "logging", @@ -878,7 +899,7 @@ "kind": "class", "path": "docforge.loaders.griffe_loader.Module", "signature": "", - "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.", + "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: Dotted import path of the module.\n docstring: Module-level documentation string, if present.\n members: Mapping of object names to their corresponding\n ``DocObject`` representations.", "members": { "path": { "name": "path", @@ -906,21 +927,21 @@ "kind": "function", "path": "docforge.loaders.griffe_loader.Module.add_object", "signature": "", - "docstring": "Add a documented object to the module.\n\nArgs:\n obj: The object to add." + "docstring": "Add a documented object to the module.\n\nArgs:\n obj: Documentation object to register as a top-level\n member of the module." }, "get_object": { "name": "get_object", "kind": "function", "path": "docforge.loaders.griffe_loader.Module.get_object", "signature": "", - "docstring": "Retrieve a member object by name.\n\nArgs:\n name: The name of the object.\n\nReturns:\n The requested DocObject." + "docstring": "Retrieve a documented object by name.\n\nArgs:\n name: Name of the object to retrieve.\n\nReturns:\n The corresponding ``DocObject`` instance.\n\nRaises:\n KeyError: If no object with the given name exists." }, "get_all_objects": { "name": "get_all_objects", "kind": "function", "path": "docforge.loaders.griffe_loader.Module.get_all_objects", "signature": "", - "docstring": "Get all top-level objects in the module.\n\nReturns:\n An iterable of DocObject instances." + "docstring": "Return all top-level documentation objects in the module.\n\nReturns:\n An iterable of ``DocObject`` instances representing the\n module's public members." } } }, @@ -929,7 +950,7 @@ "kind": "class", "path": "docforge.loaders.griffe_loader.Project", "signature": "", - "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.", + "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: Name of the project.\n modules: Mapping of module paths to ``Module`` instances.", "members": { "name": { "name": "name", @@ -950,28 +971,28 @@ "kind": "function", "path": "docforge.loaders.griffe_loader.Project.add_module", "signature": "", - "docstring": "Add a module to the project.\n\nArgs:\n module: The module to add." + "docstring": "Register a module in the project.\n\nArgs:\n module: Module instance to add to the project." }, "get_module": { "name": "get_module", "kind": "function", "path": "docforge.loaders.griffe_loader.Project.get_module", "signature": "", - "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." + "docstring": "Retrieve a module by its dotted path.\n\nArgs:\n path: Fully qualified dotted module path (for example ``pkg.module``).\n\nReturns:\n The corresponding ``Module`` instance.\n\nRaises:\n KeyError: If the module does not exist in the project." }, "get_all_modules": { "name": "get_all_modules", "kind": "function", "path": "docforge.loaders.griffe_loader.Project.get_all_modules", "signature": "", - "docstring": "Get all modules in the project.\n\nReturns:\n An iterable of Module objects." + "docstring": "Return all modules contained in the project.\n\nReturns:\n An iterable of ``Module`` instances." }, "get_module_list": { "name": "get_module_list", "kind": "function", "path": "docforge.loaders.griffe_loader.Project.get_module_list", "signature": "", - "docstring": "Get the list of all module dotted paths.\n\nReturns:\n A list of module paths." + "docstring": "Return the list of module import paths.\n\nReturns:\n A list containing the dotted paths of all modules in the project." } } }, @@ -980,7 +1001,7 @@ "kind": "class", "path": "docforge.loaders.griffe_loader.DocObject", "signature": "", - "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.", + "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: Local name of the object.\n kind: Type of object (for example ``class``, ``function``,\n ``method``, or ``attribute``).\n path: Fully qualified dotted path to the object.\n signature: Callable signature if the object represents a callable.\n docstring: Raw docstring text extracted from the source code.\n members: Mapping of member names to child ``DocObject`` instances.", "members": { "name": { "name": "name", @@ -1029,21 +1050,21 @@ "kind": "function", "path": "docforge.loaders.griffe_loader.DocObject.add_member", "signature": "", - "docstring": "Add a child member to this object (e.g., a method to a class).\n\nArgs:\n obj: The child DocObject to add." + "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." }, "get_member": { "name": "get_member", "kind": "function", "path": "docforge.loaders.griffe_loader.DocObject.get_member", "signature": "", - "docstring": "Retrieve a child member by name.\n\nArgs:\n name: The name of the member.\n\nReturns:\n The requested DocObject." + "docstring": "Retrieve a member object by name.\n\nArgs:\n name: Name of the member to retrieve.\n\nReturns:\n The corresponding ``DocObject`` instance.\n\nRaises:\n KeyError: If the member does not exist." }, "get_all_members": { "name": "get_all_members", "kind": "function", "path": "docforge.loaders.griffe_loader.DocObject.get_all_members", "signature": "", - "docstring": "Get all members of this object.\n\nReturns:\n An iterable of child DocObject instances." + "docstring": "Return all child members of the object.\n\nReturns:\n An iterable of ``DocObject`` instances representing nested members." } } }, @@ -1058,29 +1079,29 @@ "name": "discover_module_paths", "kind": "function", "path": "docforge.loaders.griffe_loader.discover_module_paths", - "signature": "", - "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." + "signature": "", + "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: Top-level package name to discover modules from.\n project_root: Root directory used to resolve module paths. If not\n provided, the current working directory is used.\n\nReturns:\n A sorted list of unique dotted module import paths.\n\nRaises:\n FileNotFoundError: If the specified package directory does not exist." }, "GriffeLoader": { "name": "GriffeLoader", "kind": "class", "path": "docforge.loaders.griffe_loader.GriffeLoader", - "signature": "", - "docstring": "Loads Python modules and extracts documentation using the Griffe introspection engine.", + "signature": "", + "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.", "members": { "load_project": { "name": "load_project", "kind": "function", "path": "docforge.loaders.griffe_loader.GriffeLoader.load_project", - "signature": "", - "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." + "signature": "", + "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 of dotted module import paths to load.\n project_name: Optional override for the project name. Defaults\n to the top-level name of the first module.\n skip_import_errors: If True, modules that fail to load will be\n skipped instead of raising an error.\n\nReturns:\n A populated ``Project`` instance containing the loaded modules.\n\nRaises:\n ValueError: If no module paths are provided.\n ImportError: If a module fails to load and\n ``skip_import_errors`` is False." }, "load_module": { "name": "load_module", "kind": "function", "path": "docforge.loaders.griffe_loader.GriffeLoader.load_module", - "signature": "", - "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." + "signature": "", + "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: Dotted import path of the module.\n\nReturns:\n A populated ``Module`` instance." } } } @@ -1093,14 +1114,14 @@ "kind": "module", "path": "docforge.models", "signature": null, - "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).", + "docstring": "Model 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\nOverview\n--------\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---", "members": { "Project": { "name": "Project", "kind": "class", "path": "docforge.models.Project", "signature": "", - "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.", + "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: Name of the project.\n modules: Mapping of module paths to ``Module`` instances.", "members": { "name": { "name": "name", @@ -1121,28 +1142,28 @@ "kind": "function", "path": "docforge.models.Project.add_module", "signature": "", - "docstring": "Add a module to the project.\n\nArgs:\n module: The module to add." + "docstring": "Register a module in the project.\n\nArgs:\n module: Module instance to add to the project." }, "get_module": { "name": "get_module", "kind": "function", "path": "docforge.models.Project.get_module", "signature": "", - "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." + "docstring": "Retrieve a module by its dotted path.\n\nArgs:\n path: Fully qualified dotted module path (for example ``pkg.module``).\n\nReturns:\n The corresponding ``Module`` instance.\n\nRaises:\n KeyError: If the module does not exist in the project." }, "get_all_modules": { "name": "get_all_modules", "kind": "function", "path": "docforge.models.Project.get_all_modules", "signature": "", - "docstring": "Get all modules in the project.\n\nReturns:\n An iterable of Module objects." + "docstring": "Return all modules contained in the project.\n\nReturns:\n An iterable of ``Module`` instances." }, "get_module_list": { "name": "get_module_list", "kind": "function", "path": "docforge.models.Project.get_module_list", "signature": "", - "docstring": "Get the list of all module dotted paths.\n\nReturns:\n A list of module paths." + "docstring": "Return the list of module import paths.\n\nReturns:\n A list containing the dotted paths of all modules in the project." } } }, @@ -1151,7 +1172,7 @@ "kind": "class", "path": "docforge.models.Module", "signature": "", - "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.", + "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: Dotted import path of the module.\n docstring: Module-level documentation string, if present.\n members: Mapping of object names to their corresponding\n ``DocObject`` representations.", "members": { "path": { "name": "path", @@ -1179,21 +1200,21 @@ "kind": "function", "path": "docforge.models.Module.add_object", "signature": "", - "docstring": "Add a documented object to the module.\n\nArgs:\n obj: The object to add." + "docstring": "Add a documented object to the module.\n\nArgs:\n obj: Documentation object to register as a top-level\n member of the module." }, "get_object": { "name": "get_object", "kind": "function", "path": "docforge.models.Module.get_object", "signature": "", - "docstring": "Retrieve a member object by name.\n\nArgs:\n name: The name of the object.\n\nReturns:\n The requested DocObject." + "docstring": "Retrieve a documented object by name.\n\nArgs:\n name: Name of the object to retrieve.\n\nReturns:\n The corresponding ``DocObject`` instance.\n\nRaises:\n KeyError: If no object with the given name exists." }, "get_all_objects": { "name": "get_all_objects", "kind": "function", "path": "docforge.models.Module.get_all_objects", "signature": "", - "docstring": "Get all top-level objects in the module.\n\nReturns:\n An iterable of DocObject instances." + "docstring": "Return all top-level documentation objects in the module.\n\nReturns:\n An iterable of ``DocObject`` instances representing the\n module's public members." } } }, @@ -1202,7 +1223,7 @@ "kind": "class", "path": "docforge.models.DocObject", "signature": "", - "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.", + "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: Local name of the object.\n kind: Type of object (for example ``class``, ``function``,\n ``method``, or ``attribute``).\n path: Fully qualified dotted path to the object.\n signature: Callable signature if the object represents a callable.\n docstring: Raw docstring text extracted from the source code.\n members: Mapping of member names to child ``DocObject`` instances.", "members": { "name": { "name": "name", @@ -1251,21 +1272,21 @@ "kind": "function", "path": "docforge.models.DocObject.add_member", "signature": "", - "docstring": "Add a child member to this object (e.g., a method to a class).\n\nArgs:\n obj: The child DocObject to add." + "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." }, "get_member": { "name": "get_member", "kind": "function", "path": "docforge.models.DocObject.get_member", "signature": "", - "docstring": "Retrieve a child member by name.\n\nArgs:\n name: The name of the member.\n\nReturns:\n The requested DocObject." + "docstring": "Retrieve a member object by name.\n\nArgs:\n name: Name of the member to retrieve.\n\nReturns:\n The corresponding ``DocObject`` instance.\n\nRaises:\n KeyError: If the member does not exist." }, "get_all_members": { "name": "get_all_members", "kind": "function", "path": "docforge.models.DocObject.get_all_members", "signature": "", - "docstring": "Get all members of this object.\n\nReturns:\n An iterable of child DocObject instances." + "docstring": "Return all child members of the object.\n\nReturns:\n An iterable of ``DocObject`` instances representing nested members." } } }, @@ -1274,7 +1295,7 @@ "kind": "module", "path": "docforge.models.module", "signature": null, - "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.", + "docstring": "Documentation 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.", "members": { "Dict": { "name": "Dict", @@ -1302,7 +1323,7 @@ "kind": "class", "path": "docforge.models.module.DocObject", "signature": "", - "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.", + "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: Local name of the object.\n kind: Type of object (for example ``class``, ``function``,\n ``method``, or ``attribute``).\n path: Fully qualified dotted path to the object.\n signature: Callable signature if the object represents a callable.\n docstring: Raw docstring text extracted from the source code.\n members: Mapping of member names to child ``DocObject`` instances.", "members": { "name": { "name": "name", @@ -1351,21 +1372,21 @@ "kind": "function", "path": "docforge.models.module.DocObject.add_member", "signature": "", - "docstring": "Add a child member to this object (e.g., a method to a class).\n\nArgs:\n obj: The child DocObject to add." + "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." }, "get_member": { "name": "get_member", "kind": "function", "path": "docforge.models.module.DocObject.get_member", "signature": "", - "docstring": "Retrieve a child member by name.\n\nArgs:\n name: The name of the member.\n\nReturns:\n The requested DocObject." + "docstring": "Retrieve a member object by name.\n\nArgs:\n name: Name of the member to retrieve.\n\nReturns:\n The corresponding ``DocObject`` instance.\n\nRaises:\n KeyError: If the member does not exist." }, "get_all_members": { "name": "get_all_members", "kind": "function", "path": "docforge.models.module.DocObject.get_all_members", "signature": "", - "docstring": "Get all members of this object.\n\nReturns:\n An iterable of child DocObject instances." + "docstring": "Return all child members of the object.\n\nReturns:\n An iterable of ``DocObject`` instances representing nested members." } } }, @@ -1373,8 +1394,8 @@ "name": "Module", "kind": "class", "path": "docforge.models.module.Module", - "signature": "", - "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.", + "signature": "", + "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: Dotted import path of the module.\n docstring: Module-level documentation string, if present.\n members: Mapping of object names to their corresponding\n ``DocObject`` representations.", "members": { "path": { "name": "path", @@ -1401,22 +1422,22 @@ "name": "add_object", "kind": "function", "path": "docforge.models.module.Module.add_object", - "signature": "", - "docstring": "Add a documented object to the module.\n\nArgs:\n obj: The object to add." + "signature": "", + "docstring": "Add a documented object to the module.\n\nArgs:\n obj: Documentation object to register as a top-level\n member of the module." }, "get_object": { "name": "get_object", "kind": "function", "path": "docforge.models.module.Module.get_object", - "signature": "", - "docstring": "Retrieve a member object by name.\n\nArgs:\n name: The name of the object.\n\nReturns:\n The requested DocObject." + "signature": "", + "docstring": "Retrieve a documented object by name.\n\nArgs:\n name: Name of the object to retrieve.\n\nReturns:\n The corresponding ``DocObject`` instance.\n\nRaises:\n KeyError: If no object with the given name exists." }, "get_all_objects": { "name": "get_all_objects", "kind": "function", "path": "docforge.models.module.Module.get_all_objects", - "signature": "", - "docstring": "Get all top-level objects in the module.\n\nReturns:\n An iterable of DocObject instances." + "signature": "", + "docstring": "Return all top-level documentation objects in the module.\n\nReturns:\n An iterable of ``DocObject`` instances representing the\n module's public members." } } } @@ -1427,7 +1448,7 @@ "kind": "module", "path": "docforge.models.object", "signature": null, - "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.", + "docstring": "Documentation 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.", "members": { "Dict": { "name": "Dict", @@ -1454,8 +1475,8 @@ "name": "DocObject", "kind": "class", "path": "docforge.models.object.DocObject", - "signature": "", - "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.", + "signature": "", + "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: Local name of the object.\n kind: Type of object (for example ``class``, ``function``,\n ``method``, or ``attribute``).\n path: Fully qualified dotted path to the object.\n signature: Callable signature if the object represents a callable.\n docstring: Raw docstring text extracted from the source code.\n members: Mapping of member names to child ``DocObject`` instances.", "members": { "name": { "name": "name", @@ -1503,22 +1524,22 @@ "name": "add_member", "kind": "function", "path": "docforge.models.object.DocObject.add_member", - "signature": "", - "docstring": "Add a child member to this object (e.g., a method to a class).\n\nArgs:\n obj: The child DocObject to add." + "signature": "", + "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." }, "get_member": { "name": "get_member", "kind": "function", "path": "docforge.models.object.DocObject.get_member", - "signature": "", - "docstring": "Retrieve a child member by name.\n\nArgs:\n name: The name of the member.\n\nReturns:\n The requested DocObject." + "signature": "", + "docstring": "Retrieve a member object by name.\n\nArgs:\n name: Name of the member to retrieve.\n\nReturns:\n The corresponding ``DocObject`` instance.\n\nRaises:\n KeyError: If the member does not exist." }, "get_all_members": { "name": "get_all_members", "kind": "function", "path": "docforge.models.object.DocObject.get_all_members", - "signature": "", - "docstring": "Get all members of this object.\n\nReturns:\n An iterable of child DocObject instances." + "signature": "", + "docstring": "Return all child members of the object.\n\nReturns:\n An iterable of ``DocObject`` instances representing nested members." } } } @@ -1529,7 +1550,7 @@ "kind": "module", "path": "docforge.models.project", "signature": null, - "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.", + "docstring": "Documentation 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.", "members": { "Dict": { "name": "Dict", @@ -1550,7 +1571,7 @@ "kind": "class", "path": "docforge.models.project.Module", "signature": "", - "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.", + "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: Dotted import path of the module.\n docstring: Module-level documentation string, if present.\n members: Mapping of object names to their corresponding\n ``DocObject`` representations.", "members": { "path": { "name": "path", @@ -1578,21 +1599,21 @@ "kind": "function", "path": "docforge.models.project.Module.add_object", "signature": "", - "docstring": "Add a documented object to the module.\n\nArgs:\n obj: The object to add." + "docstring": "Add a documented object to the module.\n\nArgs:\n obj: Documentation object to register as a top-level\n member of the module." }, "get_object": { "name": "get_object", "kind": "function", "path": "docforge.models.project.Module.get_object", "signature": "", - "docstring": "Retrieve a member object by name.\n\nArgs:\n name: The name of the object.\n\nReturns:\n The requested DocObject." + "docstring": "Retrieve a documented object by name.\n\nArgs:\n name: Name of the object to retrieve.\n\nReturns:\n The corresponding ``DocObject`` instance.\n\nRaises:\n KeyError: If no object with the given name exists." }, "get_all_objects": { "name": "get_all_objects", "kind": "function", "path": "docforge.models.project.Module.get_all_objects", "signature": "", - "docstring": "Get all top-level objects in the module.\n\nReturns:\n An iterable of DocObject instances." + "docstring": "Return all top-level documentation objects in the module.\n\nReturns:\n An iterable of ``DocObject`` instances representing the\n module's public members." } } }, @@ -1600,8 +1621,8 @@ "name": "Project", "kind": "class", "path": "docforge.models.project.Project", - "signature": "", - "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.", + "signature": "", + "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: Name of the project.\n modules: Mapping of module paths to ``Module`` instances.", "members": { "name": { "name": "name", @@ -1621,29 +1642,29 @@ "name": "add_module", "kind": "function", "path": "docforge.models.project.Project.add_module", - "signature": "", - "docstring": "Add a module to the project.\n\nArgs:\n module: The module to add." + "signature": "", + "docstring": "Register a module in the project.\n\nArgs:\n module: Module instance to add to the project." }, "get_module": { "name": "get_module", "kind": "function", "path": "docforge.models.project.Project.get_module", - "signature": "", - "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." + "signature": "", + "docstring": "Retrieve a module by its dotted path.\n\nArgs:\n path: Fully qualified dotted module path (for example ``pkg.module``).\n\nReturns:\n The corresponding ``Module`` instance.\n\nRaises:\n KeyError: If the module does not exist in the project." }, "get_all_modules": { "name": "get_all_modules", "kind": "function", "path": "docforge.models.project.Project.get_all_modules", - "signature": "", - "docstring": "Get all modules in the project.\n\nReturns:\n An iterable of Module objects." + "signature": "", + "docstring": "Return all modules contained in the project.\n\nReturns:\n An iterable of ``Module`` instances." }, "get_module_list": { "name": "get_module_list", "kind": "function", "path": "docforge.models.project.Project.get_module_list", - "signature": "", - "docstring": "Get the list of all module dotted paths.\n\nReturns:\n A list of module paths." + "signature": "", + "docstring": "Return the list of module import paths.\n\nReturns:\n A list containing the dotted paths of all modules in the project." } } } @@ -1656,14 +1677,14 @@ "kind": "module", "path": "docforge.nav", "signature": null, - "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.", + "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---", "members": { "NavSpec": { "name": "NavSpec", "kind": "class", "path": "docforge.nav.NavSpec", "signature": "", - "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.", + "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.", "members": { "home": { "name": "home", @@ -1684,14 +1705,14 @@ "kind": "function", "path": "docforge.nav.NavSpec.load", "signature": "", - "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." + "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." }, "all_patterns": { "name": "all_patterns", "kind": "function", "path": "docforge.nav.NavSpec.all_patterns", "signature": "", - "docstring": "Get all path patterns referenced in the specification.\n\nReturns:\n A list of all patterns (home plus all groups)." + "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." } } }, @@ -1700,14 +1721,14 @@ "kind": "function", "path": "docforge.nav.load_nav_spec", "signature": "", - "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." + "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." }, "ResolvedNav": { "name": "ResolvedNav", "kind": "class", "path": "docforge.nav.ResolvedNav", "signature": "", - "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.", + "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.", "members": { "home": { "name": "home", @@ -1728,7 +1749,7 @@ "kind": "function", "path": "docforge.nav.ResolvedNav.all_files", "signature": "", - "docstring": "Get an iterable of all resolved files in the navigation structure.\n\nReturns:\n An iterable of Path objects." + "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." } } }, @@ -1737,21 +1758,21 @@ "kind": "function", "path": "docforge.nav.resolve_nav", "signature": "", - "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." + "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." }, "MkDocsNavEmitter": { "name": "MkDocsNavEmitter", "kind": "class", "path": "docforge.nav.MkDocsNavEmitter", "signature": "", - "docstring": "Emitter responsible for transforming a ResolvedNav into an MkDocs-compatible\nnavigation structure.", + "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.", "members": { "emit": { "name": "emit", "kind": "function", "path": "docforge.nav.MkDocsNavEmitter.emit", "signature": "", - "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." + "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." } } }, @@ -1760,7 +1781,7 @@ "kind": "module", "path": "docforge.nav.mkdocs", "signature": null, - "docstring": "This module provides the MkDocsNavEmitter, which converts a ResolvedNav instance\ninto the specific YAML-ready list structure expected by the MkDocs 'nav'\nconfiguration.", + "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.", "members": { "Path": { "name": "Path", @@ -1795,7 +1816,7 @@ "kind": "class", "path": "docforge.nav.mkdocs.ResolvedNav", "signature": "", - "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.", + "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.", "members": { "home": { "name": "home", @@ -1816,7 +1837,7 @@ "kind": "function", "path": "docforge.nav.mkdocs.ResolvedNav.all_files", "signature": "", - "docstring": "Get an iterable of all resolved files in the navigation structure.\n\nReturns:\n An iterable of Path objects." + "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." } } }, @@ -1824,15 +1845,15 @@ "name": "MkDocsNavEmitter", "kind": "class", "path": "docforge.nav.mkdocs.MkDocsNavEmitter", - "signature": "", - "docstring": "Emitter responsible for transforming a ResolvedNav into an MkDocs-compatible\nnavigation structure.", + "signature": "", + "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.", "members": { "emit": { "name": "emit", "kind": "function", "path": "docforge.nav.mkdocs.MkDocsNavEmitter.emit", - "signature": "", - "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." + "signature": "", + "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." } } } @@ -1843,7 +1864,7 @@ "kind": "module", "path": "docforge.nav.resolver", "signature": null, - "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.", + "docstring": "Navigation resolution utilities.\n\nThis module resolves a ``NavSpec`` against the filesystem by expanding glob\npatterns and validating that referenced documentation files exist.", "members": { "Path": { "name": "Path", @@ -1885,7 +1906,7 @@ "kind": "class", "path": "docforge.nav.resolver.NavSpec", "signature": "", - "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.", + "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.", "members": { "home": { "name": "home", @@ -1906,14 +1927,14 @@ "kind": "function", "path": "docforge.nav.resolver.NavSpec.load", "signature": "", - "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." + "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." }, "all_patterns": { "name": "all_patterns", "kind": "function", "path": "docforge.nav.resolver.NavSpec.all_patterns", "signature": "", - "docstring": "Get all path patterns referenced in the specification.\n\nReturns:\n A list of all patterns (home plus all groups)." + "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." } } }, @@ -1921,8 +1942,8 @@ "name": "ResolvedNav", "kind": "class", "path": "docforge.nav.resolver.ResolvedNav", - "signature": "", - "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.", + "signature": "", + "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.", "members": { "home": { "name": "home", @@ -1942,8 +1963,8 @@ "name": "all_files", "kind": "function", "path": "docforge.nav.resolver.ResolvedNav.all_files", - "signature": "", - "docstring": "Get an iterable of all resolved files in the navigation structure.\n\nReturns:\n An iterable of Path objects." + "signature": "", + "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." } } }, @@ -1951,8 +1972,8 @@ "name": "resolve_nav", "kind": "function", "path": "docforge.nav.resolver.resolve_nav", - "signature": "", - "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." + "signature": "", + "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." }, "Optional": { "name": "Optional", @@ -1968,7 +1989,7 @@ "kind": "module", "path": "docforge.nav.spec", "signature": null, - "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).", + "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``).", "members": { "Path": { "name": "Path", @@ -2009,8 +2030,8 @@ "name": "NavSpec", "kind": "class", "path": "docforge.nav.spec.NavSpec", - "signature": "", - "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.", + "signature": "", + "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.", "members": { "home": { "name": "home", @@ -2030,15 +2051,15 @@ "name": "load", "kind": "function", "path": "docforge.nav.spec.NavSpec.load", - "signature": "", - "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." + "signature": "", + "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." }, "all_patterns": { "name": "all_patterns", "kind": "function", "path": "docforge.nav.spec.NavSpec.all_patterns", - "signature": "", - "docstring": "Get all path patterns referenced in the specification.\n\nReturns:\n A list of all patterns (home plus all groups)." + "signature": "", + "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." } } }, @@ -2046,8 +2067,8 @@ "name": "load_nav_spec", "kind": "function", "path": "docforge.nav.spec.load_nav_spec", - "signature": "", - "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." + "signature": "", + "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." } } } @@ -2058,14 +2079,14 @@ "kind": "module", "path": "docforge.renderers", "signature": null, - "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`.", + "docstring": "Renderers layer for doc-forge.\n\nThe ``docforge.renderers`` package transforms the internal documentation\nmodels into files formatted for specific documentation systems.\n\n---\n\nOverview\n--------\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\nExtending\n---------\n\nNew renderers can be added by implementing the ``DocRenderer`` protocol\ndefined in ``docforge.renderers.base``.\n\n---", "members": { "MkDocsRenderer": { "name": "MkDocsRenderer", "kind": "class", "path": "docforge.renderers.MkDocsRenderer", "signature": "", - "docstring": "Renderer that generates Markdown source files formatted for the MkDocs\n'mkdocstrings' plugin.", + "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", @@ -2079,7 +2100,14 @@ "kind": "function", "path": "docforge.renderers.MkDocsRenderer.generate_sources", "signature": "", - "docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project: The project models to render.\n out_dir: Target directory for documentation files.\n module_is_source: Module is the source folder and to be treated as the root folder." + "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 model containing modules to document.\n out_dir: Directory where generated Markdown files will be written.\n module_is_source: If True, treat the specified module as the\n documentation root rather than nesting it inside a folder." + }, + "generate_readme": { + "name": "generate_readme", + "kind": "function", + "path": "docforge.renderers.MkDocsRenderer.generate_readme", + "signature": "", + "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\n project root directory.\n- If False, README generation is currently not implemented.\n\nArgs:\n project: Project model containing documentation metadata.\n docs_dir: Directory containing generated documentation sources.\n module_is_source: Whether the module is treated as the project\n source root." } } }, @@ -2088,7 +2116,7 @@ "kind": "class", "path": "docforge.renderers.MCPRenderer", "signature": "", - "docstring": "Renderer that emits MCP-native JSON resources from docforge models.", + "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).", "members": { "name": { "name": "name", @@ -2102,7 +2130,7 @@ "kind": "function", "path": "docforge.renderers.MCPRenderer.generate_sources", "signature": "", - "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." + "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: Documentation project model to render.\n out_dir: Directory where MCP resources will be written." } } }, @@ -2111,7 +2139,7 @@ "kind": "module", "path": "docforge.renderers.base", "signature": null, - "docstring": "This module defines the base interfaces and configuration containers for\ndoc-forge renderers. All renderer implementations should adhere to the\nDocRenderer protocol.", + "docstring": "Renderer 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.", "members": { "Path": { "name": "Path", @@ -2132,7 +2160,7 @@ "kind": "class", "path": "docforge.renderers.base.Project", "signature": "", - "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.", + "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: Name of the project.\n modules: Mapping of module paths to ``Module`` instances.", "members": { "name": { "name": "name", @@ -2153,28 +2181,28 @@ "kind": "function", "path": "docforge.renderers.base.Project.add_module", "signature": "", - "docstring": "Add a module to the project.\n\nArgs:\n module: The module to add." + "docstring": "Register a module in the project.\n\nArgs:\n module: Module instance to add to the project." }, "get_module": { "name": "get_module", "kind": "function", "path": "docforge.renderers.base.Project.get_module", "signature": "", - "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." + "docstring": "Retrieve a module by its dotted path.\n\nArgs:\n path: Fully qualified dotted module path (for example ``pkg.module``).\n\nReturns:\n The corresponding ``Module`` instance.\n\nRaises:\n KeyError: If the module does not exist in the project." }, "get_all_modules": { "name": "get_all_modules", "kind": "function", "path": "docforge.renderers.base.Project.get_all_modules", "signature": "", - "docstring": "Get all modules in the project.\n\nReturns:\n An iterable of Module objects." + "docstring": "Return all modules contained in the project.\n\nReturns:\n An iterable of ``Module`` instances." }, "get_module_list": { "name": "get_module_list", "kind": "function", "path": "docforge.renderers.base.Project.get_module_list", "signature": "", - "docstring": "Get the list of all module dotted paths.\n\nReturns:\n A list of module paths." + "docstring": "Return the list of module import paths.\n\nReturns:\n A list containing the dotted paths of all modules in the project." } } }, @@ -2182,8 +2210,8 @@ "name": "RendererConfig", "kind": "class", "path": "docforge.renderers.base.RendererConfig", - "signature": "", - "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.", + "signature": "", + "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: Directory where generated documentation files will be written.\n project: Documentation project model to be rendered.", "members": { "out_dir": { "name": "out_dir", @@ -2205,8 +2233,8 @@ "name": "DocRenderer", "kind": "class", "path": "docforge.renderers.base.DocRenderer", - "signature": "", - "docstring": "Protocol defining the interface for documentation renderers.", + "signature": "", + "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.", "members": { "name": { "name": "name", @@ -2219,8 +2247,8 @@ "name": "generate_sources", "kind": "function", "path": "docforge.renderers.base.DocRenderer.generate_sources", - "signature": "", - "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." + "signature": "", + "docstring": "Generate renderer-specific documentation sources.\n\nArgs:\n project: Project model containing modules and documentation objects.\n out_dir: Directory where generated documentation sources\n should be written." } } } @@ -2266,7 +2294,7 @@ "kind": "class", "path": "docforge.renderers.mcp_renderer.Project", "signature": "", - "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.", + "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: Name of the project.\n modules: Mapping of module paths to ``Module`` instances.", "members": { "name": { "name": "name", @@ -2287,28 +2315,28 @@ "kind": "function", "path": "docforge.renderers.mcp_renderer.Project.add_module", "signature": "", - "docstring": "Add a module to the project.\n\nArgs:\n module: The module to add." + "docstring": "Register a module in the project.\n\nArgs:\n module: Module instance to add to the project." }, "get_module": { "name": "get_module", "kind": "function", "path": "docforge.renderers.mcp_renderer.Project.get_module", "signature": "", - "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." + "docstring": "Retrieve a module by its dotted path.\n\nArgs:\n path: Fully qualified dotted module path (for example ``pkg.module``).\n\nReturns:\n The corresponding ``Module`` instance.\n\nRaises:\n KeyError: If the module does not exist in the project." }, "get_all_modules": { "name": "get_all_modules", "kind": "function", "path": "docforge.renderers.mcp_renderer.Project.get_all_modules", "signature": "", - "docstring": "Get all modules in the project.\n\nReturns:\n An iterable of Module objects." + "docstring": "Return all modules contained in the project.\n\nReturns:\n An iterable of ``Module`` instances." }, "get_module_list": { "name": "get_module_list", "kind": "function", "path": "docforge.renderers.mcp_renderer.Project.get_module_list", "signature": "", - "docstring": "Get the list of all module dotted paths.\n\nReturns:\n A list of module paths." + "docstring": "Return the list of module import paths.\n\nReturns:\n A list containing the dotted paths of all modules in the project." } } }, @@ -2317,7 +2345,7 @@ "kind": "class", "path": "docforge.renderers.mcp_renderer.Module", "signature": "", - "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.", + "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: Dotted import path of the module.\n docstring: Module-level documentation string, if present.\n members: Mapping of object names to their corresponding\n ``DocObject`` representations.", "members": { "path": { "name": "path", @@ -2345,21 +2373,21 @@ "kind": "function", "path": "docforge.renderers.mcp_renderer.Module.add_object", "signature": "", - "docstring": "Add a documented object to the module.\n\nArgs:\n obj: The object to add." + "docstring": "Add a documented object to the module.\n\nArgs:\n obj: Documentation object to register as a top-level\n member of the module." }, "get_object": { "name": "get_object", "kind": "function", "path": "docforge.renderers.mcp_renderer.Module.get_object", "signature": "", - "docstring": "Retrieve a member object by name.\n\nArgs:\n name: The name of the object.\n\nReturns:\n The requested DocObject." + "docstring": "Retrieve a documented object by name.\n\nArgs:\n name: Name of the object to retrieve.\n\nReturns:\n The corresponding ``DocObject`` instance.\n\nRaises:\n KeyError: If no object with the given name exists." }, "get_all_objects": { "name": "get_all_objects", "kind": "function", "path": "docforge.renderers.mcp_renderer.Module.get_all_objects", "signature": "", - "docstring": "Get all top-level objects in the module.\n\nReturns:\n An iterable of DocObject instances." + "docstring": "Return all top-level documentation objects in the module.\n\nReturns:\n An iterable of ``DocObject`` instances representing the\n module's public members." } } }, @@ -2368,7 +2396,7 @@ "kind": "class", "path": "docforge.renderers.mcp_renderer.DocObject", "signature": "", - "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.", + "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: Local name of the object.\n kind: Type of object (for example ``class``, ``function``,\n ``method``, or ``attribute``).\n path: Fully qualified dotted path to the object.\n signature: Callable signature if the object represents a callable.\n docstring: Raw docstring text extracted from the source code.\n members: Mapping of member names to child ``DocObject`` instances.", "members": { "name": { "name": "name", @@ -2417,21 +2445,21 @@ "kind": "function", "path": "docforge.renderers.mcp_renderer.DocObject.add_member", "signature": "", - "docstring": "Add a child member to this object (e.g., a method to a class).\n\nArgs:\n obj: The child DocObject to add." + "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." }, "get_member": { "name": "get_member", "kind": "function", "path": "docforge.renderers.mcp_renderer.DocObject.get_member", "signature": "", - "docstring": "Retrieve a child member by name.\n\nArgs:\n name: The name of the member.\n\nReturns:\n The requested DocObject." + "docstring": "Retrieve a member object by name.\n\nArgs:\n name: Name of the member to retrieve.\n\nReturns:\n The corresponding ``DocObject`` instance.\n\nRaises:\n KeyError: If the member does not exist." }, "get_all_members": { "name": "get_all_members", "kind": "function", "path": "docforge.renderers.mcp_renderer.DocObject.get_all_members", "signature": "", - "docstring": "Get all members of this object.\n\nReturns:\n An iterable of child DocObject instances." + "docstring": "Return all child members of the object.\n\nReturns:\n An iterable of ``DocObject`` instances representing nested members." } } }, @@ -2439,8 +2467,8 @@ "name": "MCPRenderer", "kind": "class", "path": "docforge.renderers.mcp_renderer.MCPRenderer", - "signature": "", - "docstring": "Renderer that emits MCP-native JSON resources from docforge models.", + "signature": "", + "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).", "members": { "name": { "name": "name", @@ -2453,8 +2481,8 @@ "name": "generate_sources", "kind": "function", "path": "docforge.renderers.mcp_renderer.MCPRenderer.generate_sources", - "signature": "", - "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." + "signature": "", + "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: Documentation project model to render.\n out_dir: Directory where MCP resources will be written." } } } @@ -2465,7 +2493,7 @@ "kind": "module", "path": "docforge.renderers.mkdocs_renderer", "signature": null, - "docstring": "MkDocsRenderer\n\nGenerates Markdown source files compatible with MkDocs Material\nand mkdocstrings, ensuring:\n\n- Root index.md always exists\n- Parent package indexes are created automatically\n- Child modules are linked in parent index files", + "docstring": "MkDocs 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", "members": { "Path": { "name": "Path", @@ -2479,7 +2507,7 @@ "kind": "class", "path": "docforge.renderers.mkdocs_renderer.Project", "signature": "", - "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.", + "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: Name of the project.\n modules: Mapping of module paths to ``Module`` instances.", "members": { "name": { "name": "name", @@ -2500,28 +2528,28 @@ "kind": "function", "path": "docforge.renderers.mkdocs_renderer.Project.add_module", "signature": "", - "docstring": "Add a module to the project.\n\nArgs:\n module: The module to add." + "docstring": "Register a module in the project.\n\nArgs:\n module: Module instance to add to the project." }, "get_module": { "name": "get_module", "kind": "function", "path": "docforge.renderers.mkdocs_renderer.Project.get_module", "signature": "", - "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." + "docstring": "Retrieve a module by its dotted path.\n\nArgs:\n path: Fully qualified dotted module path (for example ``pkg.module``).\n\nReturns:\n The corresponding ``Module`` instance.\n\nRaises:\n KeyError: If the module does not exist in the project." }, "get_all_modules": { "name": "get_all_modules", "kind": "function", "path": "docforge.renderers.mkdocs_renderer.Project.get_all_modules", "signature": "", - "docstring": "Get all modules in the project.\n\nReturns:\n An iterable of Module objects." + "docstring": "Return all modules contained in the project.\n\nReturns:\n An iterable of ``Module`` instances." }, "get_module_list": { "name": "get_module_list", "kind": "function", "path": "docforge.renderers.mkdocs_renderer.Project.get_module_list", "signature": "", - "docstring": "Get the list of all module dotted paths.\n\nReturns:\n A list of module paths." + "docstring": "Return the list of module import paths.\n\nReturns:\n A list containing the dotted paths of all modules in the project." } } }, @@ -2530,7 +2558,7 @@ "kind": "class", "path": "docforge.renderers.mkdocs_renderer.Module", "signature": "", - "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.", + "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: Dotted import path of the module.\n docstring: Module-level documentation string, if present.\n members: Mapping of object names to their corresponding\n ``DocObject`` representations.", "members": { "path": { "name": "path", @@ -2558,21 +2586,21 @@ "kind": "function", "path": "docforge.renderers.mkdocs_renderer.Module.add_object", "signature": "", - "docstring": "Add a documented object to the module.\n\nArgs:\n obj: The object to add." + "docstring": "Add a documented object to the module.\n\nArgs:\n obj: Documentation object to register as a top-level\n member of the module." }, "get_object": { "name": "get_object", "kind": "function", "path": "docforge.renderers.mkdocs_renderer.Module.get_object", "signature": "", - "docstring": "Retrieve a member object by name.\n\nArgs:\n name: The name of the object.\n\nReturns:\n The requested DocObject." + "docstring": "Retrieve a documented object by name.\n\nArgs:\n name: Name of the object to retrieve.\n\nReturns:\n The corresponding ``DocObject`` instance.\n\nRaises:\n KeyError: If no object with the given name exists." }, "get_all_objects": { "name": "get_all_objects", "kind": "function", "path": "docforge.renderers.mkdocs_renderer.Module.get_all_objects", "signature": "", - "docstring": "Get all top-level objects in the module.\n\nReturns:\n An iterable of DocObject instances." + "docstring": "Return all top-level documentation objects in the module.\n\nReturns:\n An iterable of ``DocObject`` instances representing the\n module's public members." } } }, @@ -2580,8 +2608,8 @@ "name": "MkDocsRenderer", "kind": "class", "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer", - "signature": "", - "docstring": "Renderer that generates Markdown source files formatted for the MkDocs\n'mkdocstrings' plugin.", + "signature": "", + "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", @@ -2594,8 +2622,15 @@ "name": "generate_sources", "kind": "function", "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources", - "signature": "", - "docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project: The project models to render.\n out_dir: Target directory for documentation files.\n module_is_source: Module is the source folder and to be treated as the root folder." + "signature": "", + "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 model containing modules to document.\n out_dir: Directory where generated Markdown files will be written.\n module_is_source: If True, treat the specified module as the\n documentation root rather than nesting it inside a folder." + }, + "generate_readme": { + "name": "generate_readme", + "kind": "function", + "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_readme", + "signature": "", + "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\n project root directory.\n- If False, README generation is currently not implemented.\n\nArgs:\n project: Project model containing documentation metadata.\n docs_dir: Directory containing generated documentation sources.\n module_is_source: Whether the module is treated as the project\n source root." } } } @@ -2608,14 +2643,14 @@ "kind": "module", "path": "docforge.servers", "signature": null, - "docstring": null, + "docstring": "Server 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---", "members": { "MCPServer": { "name": "MCPServer", "kind": "class", "path": "docforge.servers.MCPServer", "signature": "", - "docstring": "MCP server for serving a pre-built MCP documentation bundle.", + "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.", "members": { "mcp_root": { "name": "mcp_root", @@ -2636,7 +2671,7 @@ "kind": "function", "path": "docforge.servers.MCPServer.run", "signature": "", - "docstring": "Start the MCP server.\n\nArgs:\n transport: MCP transport (default: streamable-http)" + "docstring": "Start the MCP server.\n\nArgs:\n transport: Transport mechanism used by the MCP server. Supported\n options include ``stdio``, ``sse``, and ``streamable-http``." } } }, @@ -2693,8 +2728,8 @@ "name": "MCPServer", "kind": "class", "path": "docforge.servers.mcp_server.MCPServer", - "signature": "", - "docstring": "MCP server for serving a pre-built MCP documentation bundle.", + "signature": "", + "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.", "members": { "mcp_root": { "name": "mcp_root", @@ -2714,8 +2749,8 @@ "name": "run", "kind": "function", "path": "docforge.servers.mcp_server.MCPServer.run", - "signature": "", - "docstring": "Start the MCP server.\n\nArgs:\n transport: MCP transport (default: streamable-http)" + "signature": "", + "docstring": "Start the MCP server.\n\nArgs:\n transport: Transport mechanism used by the MCP server. Supported\n options include ``stdio``, ``sse``, and ``streamable-http``." } } } diff --git a/mcp_docs/modules/docforge.loaders.griffe_loader.json b/mcp_docs/modules/docforge.loaders.griffe_loader.json index 85323ea..5b0d03b 100644 --- a/mcp_docs/modules/docforge.loaders.griffe_loader.json +++ b/mcp_docs/modules/docforge.loaders.griffe_loader.json @@ -2,7 +2,7 @@ "module": "docforge.loaders.griffe_loader", "content": { "path": "docforge.loaders.griffe_loader", - "docstring": "This module provides the GriffeLoader, which uses the 'griffe' library to\nintrospect Python source code and populate the doc-forge Project models.", + "docstring": "Utilities 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.", "objects": { "logging": { "name": "logging", @@ -65,7 +65,7 @@ "kind": "class", "path": "docforge.loaders.griffe_loader.Module", "signature": "", - "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.", + "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: Dotted import path of the module.\n docstring: Module-level documentation string, if present.\n members: Mapping of object names to their corresponding\n ``DocObject`` representations.", "members": { "path": { "name": "path", @@ -93,21 +93,21 @@ "kind": "function", "path": "docforge.loaders.griffe_loader.Module.add_object", "signature": "", - "docstring": "Add a documented object to the module.\n\nArgs:\n obj: The object to add." + "docstring": "Add a documented object to the module.\n\nArgs:\n obj: Documentation object to register as a top-level\n member of the module." }, "get_object": { "name": "get_object", "kind": "function", "path": "docforge.loaders.griffe_loader.Module.get_object", "signature": "", - "docstring": "Retrieve a member object by name.\n\nArgs:\n name: The name of the object.\n\nReturns:\n The requested DocObject." + "docstring": "Retrieve a documented object by name.\n\nArgs:\n name: Name of the object to retrieve.\n\nReturns:\n The corresponding ``DocObject`` instance.\n\nRaises:\n KeyError: If no object with the given name exists." }, "get_all_objects": { "name": "get_all_objects", "kind": "function", "path": "docforge.loaders.griffe_loader.Module.get_all_objects", "signature": "", - "docstring": "Get all top-level objects in the module.\n\nReturns:\n An iterable of DocObject instances." + "docstring": "Return all top-level documentation objects in the module.\n\nReturns:\n An iterable of ``DocObject`` instances representing the\n module's public members." } } }, @@ -116,7 +116,7 @@ "kind": "class", "path": "docforge.loaders.griffe_loader.Project", "signature": "", - "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.", + "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: Name of the project.\n modules: Mapping of module paths to ``Module`` instances.", "members": { "name": { "name": "name", @@ -137,28 +137,28 @@ "kind": "function", "path": "docforge.loaders.griffe_loader.Project.add_module", "signature": "", - "docstring": "Add a module to the project.\n\nArgs:\n module: The module to add." + "docstring": "Register a module in the project.\n\nArgs:\n module: Module instance to add to the project." }, "get_module": { "name": "get_module", "kind": "function", "path": "docforge.loaders.griffe_loader.Project.get_module", "signature": "", - "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." + "docstring": "Retrieve a module by its dotted path.\n\nArgs:\n path: Fully qualified dotted module path (for example ``pkg.module``).\n\nReturns:\n The corresponding ``Module`` instance.\n\nRaises:\n KeyError: If the module does not exist in the project." }, "get_all_modules": { "name": "get_all_modules", "kind": "function", "path": "docforge.loaders.griffe_loader.Project.get_all_modules", "signature": "", - "docstring": "Get all modules in the project.\n\nReturns:\n An iterable of Module objects." + "docstring": "Return all modules contained in the project.\n\nReturns:\n An iterable of ``Module`` instances." }, "get_module_list": { "name": "get_module_list", "kind": "function", "path": "docforge.loaders.griffe_loader.Project.get_module_list", "signature": "", - "docstring": "Get the list of all module dotted paths.\n\nReturns:\n A list of module paths." + "docstring": "Return the list of module import paths.\n\nReturns:\n A list containing the dotted paths of all modules in the project." } } }, @@ -167,7 +167,7 @@ "kind": "class", "path": "docforge.loaders.griffe_loader.DocObject", "signature": "", - "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.", + "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: Local name of the object.\n kind: Type of object (for example ``class``, ``function``,\n ``method``, or ``attribute``).\n path: Fully qualified dotted path to the object.\n signature: Callable signature if the object represents a callable.\n docstring: Raw docstring text extracted from the source code.\n members: Mapping of member names to child ``DocObject`` instances.", "members": { "name": { "name": "name", @@ -216,21 +216,21 @@ "kind": "function", "path": "docforge.loaders.griffe_loader.DocObject.add_member", "signature": "", - "docstring": "Add a child member to this object (e.g., a method to a class).\n\nArgs:\n obj: The child DocObject to add." + "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." }, "get_member": { "name": "get_member", "kind": "function", "path": "docforge.loaders.griffe_loader.DocObject.get_member", "signature": "", - "docstring": "Retrieve a child member by name.\n\nArgs:\n name: The name of the member.\n\nReturns:\n The requested DocObject." + "docstring": "Retrieve a member object by name.\n\nArgs:\n name: Name of the member to retrieve.\n\nReturns:\n The corresponding ``DocObject`` instance.\n\nRaises:\n KeyError: If the member does not exist." }, "get_all_members": { "name": "get_all_members", "kind": "function", "path": "docforge.loaders.griffe_loader.DocObject.get_all_members", "signature": "", - "docstring": "Get all members of this object.\n\nReturns:\n An iterable of child DocObject instances." + "docstring": "Return all child members of the object.\n\nReturns:\n An iterable of ``DocObject`` instances representing nested members." } } }, @@ -245,29 +245,29 @@ "name": "discover_module_paths", "kind": "function", "path": "docforge.loaders.griffe_loader.discover_module_paths", - "signature": "", - "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." + "signature": "", + "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: Top-level package name to discover modules from.\n project_root: Root directory used to resolve module paths. If not\n provided, the current working directory is used.\n\nReturns:\n A sorted list of unique dotted module import paths.\n\nRaises:\n FileNotFoundError: If the specified package directory does not exist." }, "GriffeLoader": { "name": "GriffeLoader", "kind": "class", "path": "docforge.loaders.griffe_loader.GriffeLoader", - "signature": "", - "docstring": "Loads Python modules and extracts documentation using the Griffe introspection engine.", + "signature": "", + "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.", "members": { "load_project": { "name": "load_project", "kind": "function", "path": "docforge.loaders.griffe_loader.GriffeLoader.load_project", - "signature": "", - "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." + "signature": "", + "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 of dotted module import paths to load.\n project_name: Optional override for the project name. Defaults\n to the top-level name of the first module.\n skip_import_errors: If True, modules that fail to load will be\n skipped instead of raising an error.\n\nReturns:\n A populated ``Project`` instance containing the loaded modules.\n\nRaises:\n ValueError: If no module paths are provided.\n ImportError: If a module fails to load and\n ``skip_import_errors`` is False." }, "load_module": { "name": "load_module", "kind": "function", "path": "docforge.loaders.griffe_loader.GriffeLoader.load_module", - "signature": "", - "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." + "signature": "", + "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: Dotted import path of the module.\n\nReturns:\n A populated ``Module`` instance." } } } diff --git a/mcp_docs/modules/docforge.loaders.json b/mcp_docs/modules/docforge.loaders.json index 8e833b2..ce5a3e6 100644 --- a/mcp_docs/modules/docforge.loaders.json +++ b/mcp_docs/modules/docforge.loaders.json @@ -2,28 +2,28 @@ "module": "docforge.loaders", "content": { "path": "docforge.loaders", - "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.", + "docstring": "Loader 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\nOverview\n--------\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---", "objects": { "GriffeLoader": { "name": "GriffeLoader", "kind": "class", "path": "docforge.loaders.GriffeLoader", "signature": "", - "docstring": "Loads Python modules and extracts documentation using the Griffe introspection engine.", + "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.", "members": { "load_project": { "name": "load_project", "kind": "function", "path": "docforge.loaders.GriffeLoader.load_project", "signature": "", - "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." + "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 of dotted module import paths to load.\n project_name: Optional override for the project name. Defaults\n to the top-level name of the first module.\n skip_import_errors: If True, modules that fail to load will be\n skipped instead of raising an error.\n\nReturns:\n A populated ``Project`` instance containing the loaded modules.\n\nRaises:\n ValueError: If no module paths are provided.\n ImportError: If a module fails to load and\n ``skip_import_errors`` is False." }, "load_module": { "name": "load_module", "kind": "function", "path": "docforge.loaders.GriffeLoader.load_module", "signature": "", - "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." + "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: Dotted import path of the module.\n\nReturns:\n A populated ``Module`` instance." } } }, @@ -32,14 +32,14 @@ "kind": "function", "path": "docforge.loaders.discover_module_paths", "signature": "", - "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." + "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: Top-level package name to discover modules from.\n project_root: Root directory used to resolve module paths. If not\n provided, the current working directory is used.\n\nReturns:\n A sorted list of unique dotted module import paths.\n\nRaises:\n FileNotFoundError: If the specified package directory does not exist." }, "griffe_loader": { "name": "griffe_loader", "kind": "module", "path": "docforge.loaders.griffe_loader", "signature": null, - "docstring": "This module provides the GriffeLoader, which uses the 'griffe' library to\nintrospect Python source code and populate the doc-forge Project models.", + "docstring": "Utilities 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.", "members": { "logging": { "name": "logging", @@ -102,7 +102,7 @@ "kind": "class", "path": "docforge.loaders.griffe_loader.Module", "signature": "", - "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.", + "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: Dotted import path of the module.\n docstring: Module-level documentation string, if present.\n members: Mapping of object names to their corresponding\n ``DocObject`` representations.", "members": { "path": { "name": "path", @@ -130,21 +130,21 @@ "kind": "function", "path": "docforge.loaders.griffe_loader.Module.add_object", "signature": "", - "docstring": "Add a documented object to the module.\n\nArgs:\n obj: The object to add." + "docstring": "Add a documented object to the module.\n\nArgs:\n obj: Documentation object to register as a top-level\n member of the module." }, "get_object": { "name": "get_object", "kind": "function", "path": "docforge.loaders.griffe_loader.Module.get_object", "signature": "", - "docstring": "Retrieve a member object by name.\n\nArgs:\n name: The name of the object.\n\nReturns:\n The requested DocObject." + "docstring": "Retrieve a documented object by name.\n\nArgs:\n name: Name of the object to retrieve.\n\nReturns:\n The corresponding ``DocObject`` instance.\n\nRaises:\n KeyError: If no object with the given name exists." }, "get_all_objects": { "name": "get_all_objects", "kind": "function", "path": "docforge.loaders.griffe_loader.Module.get_all_objects", "signature": "", - "docstring": "Get all top-level objects in the module.\n\nReturns:\n An iterable of DocObject instances." + "docstring": "Return all top-level documentation objects in the module.\n\nReturns:\n An iterable of ``DocObject`` instances representing the\n module's public members." } } }, @@ -153,7 +153,7 @@ "kind": "class", "path": "docforge.loaders.griffe_loader.Project", "signature": "", - "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.", + "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: Name of the project.\n modules: Mapping of module paths to ``Module`` instances.", "members": { "name": { "name": "name", @@ -174,28 +174,28 @@ "kind": "function", "path": "docforge.loaders.griffe_loader.Project.add_module", "signature": "", - "docstring": "Add a module to the project.\n\nArgs:\n module: The module to add." + "docstring": "Register a module in the project.\n\nArgs:\n module: Module instance to add to the project." }, "get_module": { "name": "get_module", "kind": "function", "path": "docforge.loaders.griffe_loader.Project.get_module", "signature": "", - "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." + "docstring": "Retrieve a module by its dotted path.\n\nArgs:\n path: Fully qualified dotted module path (for example ``pkg.module``).\n\nReturns:\n The corresponding ``Module`` instance.\n\nRaises:\n KeyError: If the module does not exist in the project." }, "get_all_modules": { "name": "get_all_modules", "kind": "function", "path": "docforge.loaders.griffe_loader.Project.get_all_modules", "signature": "", - "docstring": "Get all modules in the project.\n\nReturns:\n An iterable of Module objects." + "docstring": "Return all modules contained in the project.\n\nReturns:\n An iterable of ``Module`` instances." }, "get_module_list": { "name": "get_module_list", "kind": "function", "path": "docforge.loaders.griffe_loader.Project.get_module_list", "signature": "", - "docstring": "Get the list of all module dotted paths.\n\nReturns:\n A list of module paths." + "docstring": "Return the list of module import paths.\n\nReturns:\n A list containing the dotted paths of all modules in the project." } } }, @@ -204,7 +204,7 @@ "kind": "class", "path": "docforge.loaders.griffe_loader.DocObject", "signature": "", - "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.", + "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: Local name of the object.\n kind: Type of object (for example ``class``, ``function``,\n ``method``, or ``attribute``).\n path: Fully qualified dotted path to the object.\n signature: Callable signature if the object represents a callable.\n docstring: Raw docstring text extracted from the source code.\n members: Mapping of member names to child ``DocObject`` instances.", "members": { "name": { "name": "name", @@ -253,21 +253,21 @@ "kind": "function", "path": "docforge.loaders.griffe_loader.DocObject.add_member", "signature": "", - "docstring": "Add a child member to this object (e.g., a method to a class).\n\nArgs:\n obj: The child DocObject to add." + "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." }, "get_member": { "name": "get_member", "kind": "function", "path": "docforge.loaders.griffe_loader.DocObject.get_member", "signature": "", - "docstring": "Retrieve a child member by name.\n\nArgs:\n name: The name of the member.\n\nReturns:\n The requested DocObject." + "docstring": "Retrieve a member object by name.\n\nArgs:\n name: Name of the member to retrieve.\n\nReturns:\n The corresponding ``DocObject`` instance.\n\nRaises:\n KeyError: If the member does not exist." }, "get_all_members": { "name": "get_all_members", "kind": "function", "path": "docforge.loaders.griffe_loader.DocObject.get_all_members", "signature": "", - "docstring": "Get all members of this object.\n\nReturns:\n An iterable of child DocObject instances." + "docstring": "Return all child members of the object.\n\nReturns:\n An iterable of ``DocObject`` instances representing nested members." } } }, @@ -282,29 +282,29 @@ "name": "discover_module_paths", "kind": "function", "path": "docforge.loaders.griffe_loader.discover_module_paths", - "signature": "", - "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." + "signature": "", + "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: Top-level package name to discover modules from.\n project_root: Root directory used to resolve module paths. If not\n provided, the current working directory is used.\n\nReturns:\n A sorted list of unique dotted module import paths.\n\nRaises:\n FileNotFoundError: If the specified package directory does not exist." }, "GriffeLoader": { "name": "GriffeLoader", "kind": "class", "path": "docforge.loaders.griffe_loader.GriffeLoader", - "signature": "", - "docstring": "Loads Python modules and extracts documentation using the Griffe introspection engine.", + "signature": "", + "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.", "members": { "load_project": { "name": "load_project", "kind": "function", "path": "docforge.loaders.griffe_loader.GriffeLoader.load_project", - "signature": "", - "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." + "signature": "", + "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 of dotted module import paths to load.\n project_name: Optional override for the project name. Defaults\n to the top-level name of the first module.\n skip_import_errors: If True, modules that fail to load will be\n skipped instead of raising an error.\n\nReturns:\n A populated ``Project`` instance containing the loaded modules.\n\nRaises:\n ValueError: If no module paths are provided.\n ImportError: If a module fails to load and\n ``skip_import_errors`` is False." }, "load_module": { "name": "load_module", "kind": "function", "path": "docforge.loaders.griffe_loader.GriffeLoader.load_module", - "signature": "", - "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." + "signature": "", + "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: Dotted import path of the module.\n\nReturns:\n A populated ``Module`` instance." } } } diff --git a/mcp_docs/modules/docforge.models.json b/mcp_docs/modules/docforge.models.json index 0a4ba16..d7283f7 100644 --- a/mcp_docs/modules/docforge.models.json +++ b/mcp_docs/modules/docforge.models.json @@ -2,14 +2,14 @@ "module": "docforge.models", "content": { "path": "docforge.models", - "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).", + "docstring": "Model 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\nOverview\n--------\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---", "objects": { "Project": { "name": "Project", "kind": "class", "path": "docforge.models.Project", "signature": "", - "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.", + "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: Name of the project.\n modules: Mapping of module paths to ``Module`` instances.", "members": { "name": { "name": "name", @@ -30,28 +30,28 @@ "kind": "function", "path": "docforge.models.Project.add_module", "signature": "", - "docstring": "Add a module to the project.\n\nArgs:\n module: The module to add." + "docstring": "Register a module in the project.\n\nArgs:\n module: Module instance to add to the project." }, "get_module": { "name": "get_module", "kind": "function", "path": "docforge.models.Project.get_module", "signature": "", - "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." + "docstring": "Retrieve a module by its dotted path.\n\nArgs:\n path: Fully qualified dotted module path (for example ``pkg.module``).\n\nReturns:\n The corresponding ``Module`` instance.\n\nRaises:\n KeyError: If the module does not exist in the project." }, "get_all_modules": { "name": "get_all_modules", "kind": "function", "path": "docforge.models.Project.get_all_modules", "signature": "", - "docstring": "Get all modules in the project.\n\nReturns:\n An iterable of Module objects." + "docstring": "Return all modules contained in the project.\n\nReturns:\n An iterable of ``Module`` instances." }, "get_module_list": { "name": "get_module_list", "kind": "function", "path": "docforge.models.Project.get_module_list", "signature": "", - "docstring": "Get the list of all module dotted paths.\n\nReturns:\n A list of module paths." + "docstring": "Return the list of module import paths.\n\nReturns:\n A list containing the dotted paths of all modules in the project." } } }, @@ -60,7 +60,7 @@ "kind": "class", "path": "docforge.models.Module", "signature": "", - "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.", + "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: Dotted import path of the module.\n docstring: Module-level documentation string, if present.\n members: Mapping of object names to their corresponding\n ``DocObject`` representations.", "members": { "path": { "name": "path", @@ -88,21 +88,21 @@ "kind": "function", "path": "docforge.models.Module.add_object", "signature": "", - "docstring": "Add a documented object to the module.\n\nArgs:\n obj: The object to add." + "docstring": "Add a documented object to the module.\n\nArgs:\n obj: Documentation object to register as a top-level\n member of the module." }, "get_object": { "name": "get_object", "kind": "function", "path": "docforge.models.Module.get_object", "signature": "", - "docstring": "Retrieve a member object by name.\n\nArgs:\n name: The name of the object.\n\nReturns:\n The requested DocObject." + "docstring": "Retrieve a documented object by name.\n\nArgs:\n name: Name of the object to retrieve.\n\nReturns:\n The corresponding ``DocObject`` instance.\n\nRaises:\n KeyError: If no object with the given name exists." }, "get_all_objects": { "name": "get_all_objects", "kind": "function", "path": "docforge.models.Module.get_all_objects", "signature": "", - "docstring": "Get all top-level objects in the module.\n\nReturns:\n An iterable of DocObject instances." + "docstring": "Return all top-level documentation objects in the module.\n\nReturns:\n An iterable of ``DocObject`` instances representing the\n module's public members." } } }, @@ -111,7 +111,7 @@ "kind": "class", "path": "docforge.models.DocObject", "signature": "", - "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.", + "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: Local name of the object.\n kind: Type of object (for example ``class``, ``function``,\n ``method``, or ``attribute``).\n path: Fully qualified dotted path to the object.\n signature: Callable signature if the object represents a callable.\n docstring: Raw docstring text extracted from the source code.\n members: Mapping of member names to child ``DocObject`` instances.", "members": { "name": { "name": "name", @@ -160,21 +160,21 @@ "kind": "function", "path": "docforge.models.DocObject.add_member", "signature": "", - "docstring": "Add a child member to this object (e.g., a method to a class).\n\nArgs:\n obj: The child DocObject to add." + "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." }, "get_member": { "name": "get_member", "kind": "function", "path": "docforge.models.DocObject.get_member", "signature": "", - "docstring": "Retrieve a child member by name.\n\nArgs:\n name: The name of the member.\n\nReturns:\n The requested DocObject." + "docstring": "Retrieve a member object by name.\n\nArgs:\n name: Name of the member to retrieve.\n\nReturns:\n The corresponding ``DocObject`` instance.\n\nRaises:\n KeyError: If the member does not exist." }, "get_all_members": { "name": "get_all_members", "kind": "function", "path": "docforge.models.DocObject.get_all_members", "signature": "", - "docstring": "Get all members of this object.\n\nReturns:\n An iterable of child DocObject instances." + "docstring": "Return all child members of the object.\n\nReturns:\n An iterable of ``DocObject`` instances representing nested members." } } }, @@ -183,7 +183,7 @@ "kind": "module", "path": "docforge.models.module", "signature": null, - "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.", + "docstring": "Documentation 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.", "members": { "Dict": { "name": "Dict", @@ -211,7 +211,7 @@ "kind": "class", "path": "docforge.models.module.DocObject", "signature": "", - "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.", + "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: Local name of the object.\n kind: Type of object (for example ``class``, ``function``,\n ``method``, or ``attribute``).\n path: Fully qualified dotted path to the object.\n signature: Callable signature if the object represents a callable.\n docstring: Raw docstring text extracted from the source code.\n members: Mapping of member names to child ``DocObject`` instances.", "members": { "name": { "name": "name", @@ -260,21 +260,21 @@ "kind": "function", "path": "docforge.models.module.DocObject.add_member", "signature": "", - "docstring": "Add a child member to this object (e.g., a method to a class).\n\nArgs:\n obj: The child DocObject to add." + "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." }, "get_member": { "name": "get_member", "kind": "function", "path": "docforge.models.module.DocObject.get_member", "signature": "", - "docstring": "Retrieve a child member by name.\n\nArgs:\n name: The name of the member.\n\nReturns:\n The requested DocObject." + "docstring": "Retrieve a member object by name.\n\nArgs:\n name: Name of the member to retrieve.\n\nReturns:\n The corresponding ``DocObject`` instance.\n\nRaises:\n KeyError: If the member does not exist." }, "get_all_members": { "name": "get_all_members", "kind": "function", "path": "docforge.models.module.DocObject.get_all_members", "signature": "", - "docstring": "Get all members of this object.\n\nReturns:\n An iterable of child DocObject instances." + "docstring": "Return all child members of the object.\n\nReturns:\n An iterable of ``DocObject`` instances representing nested members." } } }, @@ -282,8 +282,8 @@ "name": "Module", "kind": "class", "path": "docforge.models.module.Module", - "signature": "", - "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.", + "signature": "", + "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: Dotted import path of the module.\n docstring: Module-level documentation string, if present.\n members: Mapping of object names to their corresponding\n ``DocObject`` representations.", "members": { "path": { "name": "path", @@ -310,22 +310,22 @@ "name": "add_object", "kind": "function", "path": "docforge.models.module.Module.add_object", - "signature": "", - "docstring": "Add a documented object to the module.\n\nArgs:\n obj: The object to add." + "signature": "", + "docstring": "Add a documented object to the module.\n\nArgs:\n obj: Documentation object to register as a top-level\n member of the module." }, "get_object": { "name": "get_object", "kind": "function", "path": "docforge.models.module.Module.get_object", - "signature": "", - "docstring": "Retrieve a member object by name.\n\nArgs:\n name: The name of the object.\n\nReturns:\n The requested DocObject." + "signature": "", + "docstring": "Retrieve a documented object by name.\n\nArgs:\n name: Name of the object to retrieve.\n\nReturns:\n The corresponding ``DocObject`` instance.\n\nRaises:\n KeyError: If no object with the given name exists." }, "get_all_objects": { "name": "get_all_objects", "kind": "function", "path": "docforge.models.module.Module.get_all_objects", - "signature": "", - "docstring": "Get all top-level objects in the module.\n\nReturns:\n An iterable of DocObject instances." + "signature": "", + "docstring": "Return all top-level documentation objects in the module.\n\nReturns:\n An iterable of ``DocObject`` instances representing the\n module's public members." } } } @@ -336,7 +336,7 @@ "kind": "module", "path": "docforge.models.object", "signature": null, - "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.", + "docstring": "Documentation 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.", "members": { "Dict": { "name": "Dict", @@ -363,8 +363,8 @@ "name": "DocObject", "kind": "class", "path": "docforge.models.object.DocObject", - "signature": "", - "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.", + "signature": "", + "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: Local name of the object.\n kind: Type of object (for example ``class``, ``function``,\n ``method``, or ``attribute``).\n path: Fully qualified dotted path to the object.\n signature: Callable signature if the object represents a callable.\n docstring: Raw docstring text extracted from the source code.\n members: Mapping of member names to child ``DocObject`` instances.", "members": { "name": { "name": "name", @@ -412,22 +412,22 @@ "name": "add_member", "kind": "function", "path": "docforge.models.object.DocObject.add_member", - "signature": "", - "docstring": "Add a child member to this object (e.g., a method to a class).\n\nArgs:\n obj: The child DocObject to add." + "signature": "", + "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." }, "get_member": { "name": "get_member", "kind": "function", "path": "docforge.models.object.DocObject.get_member", - "signature": "", - "docstring": "Retrieve a child member by name.\n\nArgs:\n name: The name of the member.\n\nReturns:\n The requested DocObject." + "signature": "", + "docstring": "Retrieve a member object by name.\n\nArgs:\n name: Name of the member to retrieve.\n\nReturns:\n The corresponding ``DocObject`` instance.\n\nRaises:\n KeyError: If the member does not exist." }, "get_all_members": { "name": "get_all_members", "kind": "function", "path": "docforge.models.object.DocObject.get_all_members", - "signature": "", - "docstring": "Get all members of this object.\n\nReturns:\n An iterable of child DocObject instances." + "signature": "", + "docstring": "Return all child members of the object.\n\nReturns:\n An iterable of ``DocObject`` instances representing nested members." } } } @@ -438,7 +438,7 @@ "kind": "module", "path": "docforge.models.project", "signature": null, - "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.", + "docstring": "Documentation 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.", "members": { "Dict": { "name": "Dict", @@ -459,7 +459,7 @@ "kind": "class", "path": "docforge.models.project.Module", "signature": "", - "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.", + "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: Dotted import path of the module.\n docstring: Module-level documentation string, if present.\n members: Mapping of object names to their corresponding\n ``DocObject`` representations.", "members": { "path": { "name": "path", @@ -487,21 +487,21 @@ "kind": "function", "path": "docforge.models.project.Module.add_object", "signature": "", - "docstring": "Add a documented object to the module.\n\nArgs:\n obj: The object to add." + "docstring": "Add a documented object to the module.\n\nArgs:\n obj: Documentation object to register as a top-level\n member of the module." }, "get_object": { "name": "get_object", "kind": "function", "path": "docforge.models.project.Module.get_object", "signature": "", - "docstring": "Retrieve a member object by name.\n\nArgs:\n name: The name of the object.\n\nReturns:\n The requested DocObject." + "docstring": "Retrieve a documented object by name.\n\nArgs:\n name: Name of the object to retrieve.\n\nReturns:\n The corresponding ``DocObject`` instance.\n\nRaises:\n KeyError: If no object with the given name exists." }, "get_all_objects": { "name": "get_all_objects", "kind": "function", "path": "docforge.models.project.Module.get_all_objects", "signature": "", - "docstring": "Get all top-level objects in the module.\n\nReturns:\n An iterable of DocObject instances." + "docstring": "Return all top-level documentation objects in the module.\n\nReturns:\n An iterable of ``DocObject`` instances representing the\n module's public members." } } }, @@ -509,8 +509,8 @@ "name": "Project", "kind": "class", "path": "docforge.models.project.Project", - "signature": "", - "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.", + "signature": "", + "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: Name of the project.\n modules: Mapping of module paths to ``Module`` instances.", "members": { "name": { "name": "name", @@ -530,29 +530,29 @@ "name": "add_module", "kind": "function", "path": "docforge.models.project.Project.add_module", - "signature": "", - "docstring": "Add a module to the project.\n\nArgs:\n module: The module to add." + "signature": "", + "docstring": "Register a module in the project.\n\nArgs:\n module: Module instance to add to the project." }, "get_module": { "name": "get_module", "kind": "function", "path": "docforge.models.project.Project.get_module", - "signature": "", - "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." + "signature": "", + "docstring": "Retrieve a module by its dotted path.\n\nArgs:\n path: Fully qualified dotted module path (for example ``pkg.module``).\n\nReturns:\n The corresponding ``Module`` instance.\n\nRaises:\n KeyError: If the module does not exist in the project." }, "get_all_modules": { "name": "get_all_modules", "kind": "function", "path": "docforge.models.project.Project.get_all_modules", - "signature": "", - "docstring": "Get all modules in the project.\n\nReturns:\n An iterable of Module objects." + "signature": "", + "docstring": "Return all modules contained in the project.\n\nReturns:\n An iterable of ``Module`` instances." }, "get_module_list": { "name": "get_module_list", "kind": "function", "path": "docforge.models.project.Project.get_module_list", - "signature": "", - "docstring": "Get the list of all module dotted paths.\n\nReturns:\n A list of module paths." + "signature": "", + "docstring": "Return the list of module import paths.\n\nReturns:\n A list containing the dotted paths of all modules in the project." } } } diff --git a/mcp_docs/modules/docforge.models.module.json b/mcp_docs/modules/docforge.models.module.json index ef86e1a..06eac26 100644 --- a/mcp_docs/modules/docforge.models.module.json +++ b/mcp_docs/modules/docforge.models.module.json @@ -2,7 +2,7 @@ "module": "docforge.models.module", "content": { "path": "docforge.models.module", - "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.", + "docstring": "Documentation 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.", "objects": { "Dict": { "name": "Dict", @@ -30,7 +30,7 @@ "kind": "class", "path": "docforge.models.module.DocObject", "signature": "", - "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.", + "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: Local name of the object.\n kind: Type of object (for example ``class``, ``function``,\n ``method``, or ``attribute``).\n path: Fully qualified dotted path to the object.\n signature: Callable signature if the object represents a callable.\n docstring: Raw docstring text extracted from the source code.\n members: Mapping of member names to child ``DocObject`` instances.", "members": { "name": { "name": "name", @@ -79,21 +79,21 @@ "kind": "function", "path": "docforge.models.module.DocObject.add_member", "signature": "", - "docstring": "Add a child member to this object (e.g., a method to a class).\n\nArgs:\n obj: The child DocObject to add." + "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." }, "get_member": { "name": "get_member", "kind": "function", "path": "docforge.models.module.DocObject.get_member", "signature": "", - "docstring": "Retrieve a child member by name.\n\nArgs:\n name: The name of the member.\n\nReturns:\n The requested DocObject." + "docstring": "Retrieve a member object by name.\n\nArgs:\n name: Name of the member to retrieve.\n\nReturns:\n The corresponding ``DocObject`` instance.\n\nRaises:\n KeyError: If the member does not exist." }, "get_all_members": { "name": "get_all_members", "kind": "function", "path": "docforge.models.module.DocObject.get_all_members", "signature": "", - "docstring": "Get all members of this object.\n\nReturns:\n An iterable of child DocObject instances." + "docstring": "Return all child members of the object.\n\nReturns:\n An iterable of ``DocObject`` instances representing nested members." } } }, @@ -101,8 +101,8 @@ "name": "Module", "kind": "class", "path": "docforge.models.module.Module", - "signature": "", - "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.", + "signature": "", + "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: Dotted import path of the module.\n docstring: Module-level documentation string, if present.\n members: Mapping of object names to their corresponding\n ``DocObject`` representations.", "members": { "path": { "name": "path", @@ -129,22 +129,22 @@ "name": "add_object", "kind": "function", "path": "docforge.models.module.Module.add_object", - "signature": "", - "docstring": "Add a documented object to the module.\n\nArgs:\n obj: The object to add." + "signature": "", + "docstring": "Add a documented object to the module.\n\nArgs:\n obj: Documentation object to register as a top-level\n member of the module." }, "get_object": { "name": "get_object", "kind": "function", "path": "docforge.models.module.Module.get_object", - "signature": "", - "docstring": "Retrieve a member object by name.\n\nArgs:\n name: The name of the object.\n\nReturns:\n The requested DocObject." + "signature": "", + "docstring": "Retrieve a documented object by name.\n\nArgs:\n name: Name of the object to retrieve.\n\nReturns:\n The corresponding ``DocObject`` instance.\n\nRaises:\n KeyError: If no object with the given name exists." }, "get_all_objects": { "name": "get_all_objects", "kind": "function", "path": "docforge.models.module.Module.get_all_objects", - "signature": "", - "docstring": "Get all top-level objects in the module.\n\nReturns:\n An iterable of DocObject instances." + "signature": "", + "docstring": "Return all top-level documentation objects in the module.\n\nReturns:\n An iterable of ``DocObject`` instances representing the\n module's public members." } } } diff --git a/mcp_docs/modules/docforge.models.object.json b/mcp_docs/modules/docforge.models.object.json index 5f162f6..2625cfa 100644 --- a/mcp_docs/modules/docforge.models.object.json +++ b/mcp_docs/modules/docforge.models.object.json @@ -2,7 +2,7 @@ "module": "docforge.models.object", "content": { "path": "docforge.models.object", - "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.", + "docstring": "Documentation 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.", "objects": { "Dict": { "name": "Dict", @@ -29,8 +29,8 @@ "name": "DocObject", "kind": "class", "path": "docforge.models.object.DocObject", - "signature": "", - "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.", + "signature": "", + "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: Local name of the object.\n kind: Type of object (for example ``class``, ``function``,\n ``method``, or ``attribute``).\n path: Fully qualified dotted path to the object.\n signature: Callable signature if the object represents a callable.\n docstring: Raw docstring text extracted from the source code.\n members: Mapping of member names to child ``DocObject`` instances.", "members": { "name": { "name": "name", @@ -78,22 +78,22 @@ "name": "add_member", "kind": "function", "path": "docforge.models.object.DocObject.add_member", - "signature": "", - "docstring": "Add a child member to this object (e.g., a method to a class).\n\nArgs:\n obj: The child DocObject to add." + "signature": "", + "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." }, "get_member": { "name": "get_member", "kind": "function", "path": "docforge.models.object.DocObject.get_member", - "signature": "", - "docstring": "Retrieve a child member by name.\n\nArgs:\n name: The name of the member.\n\nReturns:\n The requested DocObject." + "signature": "", + "docstring": "Retrieve a member object by name.\n\nArgs:\n name: Name of the member to retrieve.\n\nReturns:\n The corresponding ``DocObject`` instance.\n\nRaises:\n KeyError: If the member does not exist." }, "get_all_members": { "name": "get_all_members", "kind": "function", "path": "docforge.models.object.DocObject.get_all_members", - "signature": "", - "docstring": "Get all members of this object.\n\nReturns:\n An iterable of child DocObject instances." + "signature": "", + "docstring": "Return all child members of the object.\n\nReturns:\n An iterable of ``DocObject`` instances representing nested members." } } } diff --git a/mcp_docs/modules/docforge.models.project.json b/mcp_docs/modules/docforge.models.project.json index 83b1ed1..d53aeba 100644 --- a/mcp_docs/modules/docforge.models.project.json +++ b/mcp_docs/modules/docforge.models.project.json @@ -2,7 +2,7 @@ "module": "docforge.models.project", "content": { "path": "docforge.models.project", - "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.", + "docstring": "Documentation 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.", "objects": { "Dict": { "name": "Dict", @@ -23,7 +23,7 @@ "kind": "class", "path": "docforge.models.project.Module", "signature": "", - "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.", + "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: Dotted import path of the module.\n docstring: Module-level documentation string, if present.\n members: Mapping of object names to their corresponding\n ``DocObject`` representations.", "members": { "path": { "name": "path", @@ -51,21 +51,21 @@ "kind": "function", "path": "docforge.models.project.Module.add_object", "signature": "", - "docstring": "Add a documented object to the module.\n\nArgs:\n obj: The object to add." + "docstring": "Add a documented object to the module.\n\nArgs:\n obj: Documentation object to register as a top-level\n member of the module." }, "get_object": { "name": "get_object", "kind": "function", "path": "docforge.models.project.Module.get_object", "signature": "", - "docstring": "Retrieve a member object by name.\n\nArgs:\n name: The name of the object.\n\nReturns:\n The requested DocObject." + "docstring": "Retrieve a documented object by name.\n\nArgs:\n name: Name of the object to retrieve.\n\nReturns:\n The corresponding ``DocObject`` instance.\n\nRaises:\n KeyError: If no object with the given name exists." }, "get_all_objects": { "name": "get_all_objects", "kind": "function", "path": "docforge.models.project.Module.get_all_objects", "signature": "", - "docstring": "Get all top-level objects in the module.\n\nReturns:\n An iterable of DocObject instances." + "docstring": "Return all top-level documentation objects in the module.\n\nReturns:\n An iterable of ``DocObject`` instances representing the\n module's public members." } } }, @@ -73,8 +73,8 @@ "name": "Project", "kind": "class", "path": "docforge.models.project.Project", - "signature": "", - "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.", + "signature": "", + "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: Name of the project.\n modules: Mapping of module paths to ``Module`` instances.", "members": { "name": { "name": "name", @@ -94,29 +94,29 @@ "name": "add_module", "kind": "function", "path": "docforge.models.project.Project.add_module", - "signature": "", - "docstring": "Add a module to the project.\n\nArgs:\n module: The module to add." + "signature": "", + "docstring": "Register a module in the project.\n\nArgs:\n module: Module instance to add to the project." }, "get_module": { "name": "get_module", "kind": "function", "path": "docforge.models.project.Project.get_module", - "signature": "", - "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." + "signature": "", + "docstring": "Retrieve a module by its dotted path.\n\nArgs:\n path: Fully qualified dotted module path (for example ``pkg.module``).\n\nReturns:\n The corresponding ``Module`` instance.\n\nRaises:\n KeyError: If the module does not exist in the project." }, "get_all_modules": { "name": "get_all_modules", "kind": "function", "path": "docforge.models.project.Project.get_all_modules", - "signature": "", - "docstring": "Get all modules in the project.\n\nReturns:\n An iterable of Module objects." + "signature": "", + "docstring": "Return all modules contained in the project.\n\nReturns:\n An iterable of ``Module`` instances." }, "get_module_list": { "name": "get_module_list", "kind": "function", "path": "docforge.models.project.Project.get_module_list", - "signature": "", - "docstring": "Get the list of all module dotted paths.\n\nReturns:\n A list of module paths." + "signature": "", + "docstring": "Return the list of module import paths.\n\nReturns:\n A list containing the dotted paths of all modules in the project." } } } diff --git a/mcp_docs/modules/docforge.nav.json b/mcp_docs/modules/docforge.nav.json index 164fb34..7c913c2 100644 --- a/mcp_docs/modules/docforge.nav.json +++ b/mcp_docs/modules/docforge.nav.json @@ -2,14 +2,14 @@ "module": "docforge.nav", "content": { "path": "docforge.nav", - "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.", + "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---", "objects": { "NavSpec": { "name": "NavSpec", "kind": "class", "path": "docforge.nav.NavSpec", "signature": "", - "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.", + "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.", "members": { "home": { "name": "home", @@ -30,14 +30,14 @@ "kind": "function", "path": "docforge.nav.NavSpec.load", "signature": "", - "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." + "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." }, "all_patterns": { "name": "all_patterns", "kind": "function", "path": "docforge.nav.NavSpec.all_patterns", "signature": "", - "docstring": "Get all path patterns referenced in the specification.\n\nReturns:\n A list of all patterns (home plus all groups)." + "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." } } }, @@ -46,14 +46,14 @@ "kind": "function", "path": "docforge.nav.load_nav_spec", "signature": "", - "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." + "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." }, "ResolvedNav": { "name": "ResolvedNav", "kind": "class", "path": "docforge.nav.ResolvedNav", "signature": "", - "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.", + "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.", "members": { "home": { "name": "home", @@ -74,7 +74,7 @@ "kind": "function", "path": "docforge.nav.ResolvedNav.all_files", "signature": "", - "docstring": "Get an iterable of all resolved files in the navigation structure.\n\nReturns:\n An iterable of Path objects." + "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." } } }, @@ -83,21 +83,21 @@ "kind": "function", "path": "docforge.nav.resolve_nav", "signature": "", - "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." + "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." }, "MkDocsNavEmitter": { "name": "MkDocsNavEmitter", "kind": "class", "path": "docforge.nav.MkDocsNavEmitter", "signature": "", - "docstring": "Emitter responsible for transforming a ResolvedNav into an MkDocs-compatible\nnavigation structure.", + "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.", "members": { "emit": { "name": "emit", "kind": "function", "path": "docforge.nav.MkDocsNavEmitter.emit", "signature": "", - "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." + "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." } } }, @@ -106,7 +106,7 @@ "kind": "module", "path": "docforge.nav.mkdocs", "signature": null, - "docstring": "This module provides the MkDocsNavEmitter, which converts a ResolvedNav instance\ninto the specific YAML-ready list structure expected by the MkDocs 'nav'\nconfiguration.", + "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.", "members": { "Path": { "name": "Path", @@ -141,7 +141,7 @@ "kind": "class", "path": "docforge.nav.mkdocs.ResolvedNav", "signature": "", - "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.", + "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.", "members": { "home": { "name": "home", @@ -162,7 +162,7 @@ "kind": "function", "path": "docforge.nav.mkdocs.ResolvedNav.all_files", "signature": "", - "docstring": "Get an iterable of all resolved files in the navigation structure.\n\nReturns:\n An iterable of Path objects." + "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." } } }, @@ -170,15 +170,15 @@ "name": "MkDocsNavEmitter", "kind": "class", "path": "docforge.nav.mkdocs.MkDocsNavEmitter", - "signature": "", - "docstring": "Emitter responsible for transforming a ResolvedNav into an MkDocs-compatible\nnavigation structure.", + "signature": "", + "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.", "members": { "emit": { "name": "emit", "kind": "function", "path": "docforge.nav.mkdocs.MkDocsNavEmitter.emit", - "signature": "", - "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." + "signature": "", + "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." } } } @@ -189,7 +189,7 @@ "kind": "module", "path": "docforge.nav.resolver", "signature": null, - "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.", + "docstring": "Navigation resolution utilities.\n\nThis module resolves a ``NavSpec`` against the filesystem by expanding glob\npatterns and validating that referenced documentation files exist.", "members": { "Path": { "name": "Path", @@ -231,7 +231,7 @@ "kind": "class", "path": "docforge.nav.resolver.NavSpec", "signature": "", - "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.", + "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.", "members": { "home": { "name": "home", @@ -252,14 +252,14 @@ "kind": "function", "path": "docforge.nav.resolver.NavSpec.load", "signature": "", - "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." + "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." }, "all_patterns": { "name": "all_patterns", "kind": "function", "path": "docforge.nav.resolver.NavSpec.all_patterns", "signature": "", - "docstring": "Get all path patterns referenced in the specification.\n\nReturns:\n A list of all patterns (home plus all groups)." + "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." } } }, @@ -267,8 +267,8 @@ "name": "ResolvedNav", "kind": "class", "path": "docforge.nav.resolver.ResolvedNav", - "signature": "", - "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.", + "signature": "", + "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.", "members": { "home": { "name": "home", @@ -288,8 +288,8 @@ "name": "all_files", "kind": "function", "path": "docforge.nav.resolver.ResolvedNav.all_files", - "signature": "", - "docstring": "Get an iterable of all resolved files in the navigation structure.\n\nReturns:\n An iterable of Path objects." + "signature": "", + "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." } } }, @@ -297,8 +297,8 @@ "name": "resolve_nav", "kind": "function", "path": "docforge.nav.resolver.resolve_nav", - "signature": "", - "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." + "signature": "", + "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." }, "Optional": { "name": "Optional", @@ -314,7 +314,7 @@ "kind": "module", "path": "docforge.nav.spec", "signature": null, - "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).", + "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``).", "members": { "Path": { "name": "Path", @@ -355,8 +355,8 @@ "name": "NavSpec", "kind": "class", "path": "docforge.nav.spec.NavSpec", - "signature": "", - "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.", + "signature": "", + "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.", "members": { "home": { "name": "home", @@ -376,15 +376,15 @@ "name": "load", "kind": "function", "path": "docforge.nav.spec.NavSpec.load", - "signature": "", - "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." + "signature": "", + "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." }, "all_patterns": { "name": "all_patterns", "kind": "function", "path": "docforge.nav.spec.NavSpec.all_patterns", - "signature": "", - "docstring": "Get all path patterns referenced in the specification.\n\nReturns:\n A list of all patterns (home plus all groups)." + "signature": "", + "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." } } }, @@ -392,8 +392,8 @@ "name": "load_nav_spec", "kind": "function", "path": "docforge.nav.spec.load_nav_spec", - "signature": "", - "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." + "signature": "", + "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." } } } diff --git a/mcp_docs/modules/docforge.nav.mkdocs.json b/mcp_docs/modules/docforge.nav.mkdocs.json index 77b18a4..a5da244 100644 --- a/mcp_docs/modules/docforge.nav.mkdocs.json +++ b/mcp_docs/modules/docforge.nav.mkdocs.json @@ -2,7 +2,7 @@ "module": "docforge.nav.mkdocs", "content": { "path": "docforge.nav.mkdocs", - "docstring": "This module provides the MkDocsNavEmitter, which converts a ResolvedNav instance\ninto the specific YAML-ready list structure expected by the MkDocs 'nav'\nconfiguration.", + "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.", "objects": { "Path": { "name": "Path", @@ -37,7 +37,7 @@ "kind": "class", "path": "docforge.nav.mkdocs.ResolvedNav", "signature": "", - "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.", + "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.", "members": { "home": { "name": "home", @@ -58,7 +58,7 @@ "kind": "function", "path": "docforge.nav.mkdocs.ResolvedNav.all_files", "signature": "", - "docstring": "Get an iterable of all resolved files in the navigation structure.\n\nReturns:\n An iterable of Path objects." + "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." } } }, @@ -66,15 +66,15 @@ "name": "MkDocsNavEmitter", "kind": "class", "path": "docforge.nav.mkdocs.MkDocsNavEmitter", - "signature": "", - "docstring": "Emitter responsible for transforming a ResolvedNav into an MkDocs-compatible\nnavigation structure.", + "signature": "", + "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.", "members": { "emit": { "name": "emit", "kind": "function", "path": "docforge.nav.mkdocs.MkDocsNavEmitter.emit", - "signature": "", - "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." + "signature": "", + "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." } } } diff --git a/mcp_docs/modules/docforge.nav.resolver.json b/mcp_docs/modules/docforge.nav.resolver.json index 4c12de7..1f75460 100644 --- a/mcp_docs/modules/docforge.nav.resolver.json +++ b/mcp_docs/modules/docforge.nav.resolver.json @@ -2,7 +2,7 @@ "module": "docforge.nav.resolver", "content": { "path": "docforge.nav.resolver", - "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.", + "docstring": "Navigation resolution utilities.\n\nThis module resolves a ``NavSpec`` against the filesystem by expanding glob\npatterns and validating that referenced documentation files exist.", "objects": { "Path": { "name": "Path", @@ -44,7 +44,7 @@ "kind": "class", "path": "docforge.nav.resolver.NavSpec", "signature": "", - "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.", + "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.", "members": { "home": { "name": "home", @@ -65,14 +65,14 @@ "kind": "function", "path": "docforge.nav.resolver.NavSpec.load", "signature": "", - "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." + "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." }, "all_patterns": { "name": "all_patterns", "kind": "function", "path": "docforge.nav.resolver.NavSpec.all_patterns", "signature": "", - "docstring": "Get all path patterns referenced in the specification.\n\nReturns:\n A list of all patterns (home plus all groups)." + "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." } } }, @@ -80,8 +80,8 @@ "name": "ResolvedNav", "kind": "class", "path": "docforge.nav.resolver.ResolvedNav", - "signature": "", - "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.", + "signature": "", + "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.", "members": { "home": { "name": "home", @@ -101,8 +101,8 @@ "name": "all_files", "kind": "function", "path": "docforge.nav.resolver.ResolvedNav.all_files", - "signature": "", - "docstring": "Get an iterable of all resolved files in the navigation structure.\n\nReturns:\n An iterable of Path objects." + "signature": "", + "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." } } }, @@ -110,8 +110,8 @@ "name": "resolve_nav", "kind": "function", "path": "docforge.nav.resolver.resolve_nav", - "signature": "", - "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." + "signature": "", + "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." }, "Optional": { "name": "Optional", diff --git a/mcp_docs/modules/docforge.nav.spec.json b/mcp_docs/modules/docforge.nav.spec.json index e0224ff..d434545 100644 --- a/mcp_docs/modules/docforge.nav.spec.json +++ b/mcp_docs/modules/docforge.nav.spec.json @@ -2,7 +2,7 @@ "module": "docforge.nav.spec", "content": { "path": "docforge.nav.spec", - "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).", + "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``).", "objects": { "Path": { "name": "Path", @@ -43,8 +43,8 @@ "name": "NavSpec", "kind": "class", "path": "docforge.nav.spec.NavSpec", - "signature": "", - "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.", + "signature": "", + "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.", "members": { "home": { "name": "home", @@ -64,15 +64,15 @@ "name": "load", "kind": "function", "path": "docforge.nav.spec.NavSpec.load", - "signature": "", - "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." + "signature": "", + "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." }, "all_patterns": { "name": "all_patterns", "kind": "function", "path": "docforge.nav.spec.NavSpec.all_patterns", - "signature": "", - "docstring": "Get all path patterns referenced in the specification.\n\nReturns:\n A list of all patterns (home plus all groups)." + "signature": "", + "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." } } }, @@ -80,8 +80,8 @@ "name": "load_nav_spec", "kind": "function", "path": "docforge.nav.spec.load_nav_spec", - "signature": "", - "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." + "signature": "", + "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." } } } diff --git a/mcp_docs/modules/docforge.renderers.base.json b/mcp_docs/modules/docforge.renderers.base.json index da95b43..237b78c 100644 --- a/mcp_docs/modules/docforge.renderers.base.json +++ b/mcp_docs/modules/docforge.renderers.base.json @@ -2,7 +2,7 @@ "module": "docforge.renderers.base", "content": { "path": "docforge.renderers.base", - "docstring": "This module defines the base interfaces and configuration containers for\ndoc-forge renderers. All renderer implementations should adhere to the\nDocRenderer protocol.", + "docstring": "Renderer 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.", "objects": { "Path": { "name": "Path", @@ -23,7 +23,7 @@ "kind": "class", "path": "docforge.renderers.base.Project", "signature": "", - "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.", + "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: Name of the project.\n modules: Mapping of module paths to ``Module`` instances.", "members": { "name": { "name": "name", @@ -44,28 +44,28 @@ "kind": "function", "path": "docforge.renderers.base.Project.add_module", "signature": "", - "docstring": "Add a module to the project.\n\nArgs:\n module: The module to add." + "docstring": "Register a module in the project.\n\nArgs:\n module: Module instance to add to the project." }, "get_module": { "name": "get_module", "kind": "function", "path": "docforge.renderers.base.Project.get_module", "signature": "", - "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." + "docstring": "Retrieve a module by its dotted path.\n\nArgs:\n path: Fully qualified dotted module path (for example ``pkg.module``).\n\nReturns:\n The corresponding ``Module`` instance.\n\nRaises:\n KeyError: If the module does not exist in the project." }, "get_all_modules": { "name": "get_all_modules", "kind": "function", "path": "docforge.renderers.base.Project.get_all_modules", "signature": "", - "docstring": "Get all modules in the project.\n\nReturns:\n An iterable of Module objects." + "docstring": "Return all modules contained in the project.\n\nReturns:\n An iterable of ``Module`` instances." }, "get_module_list": { "name": "get_module_list", "kind": "function", "path": "docforge.renderers.base.Project.get_module_list", "signature": "", - "docstring": "Get the list of all module dotted paths.\n\nReturns:\n A list of module paths." + "docstring": "Return the list of module import paths.\n\nReturns:\n A list containing the dotted paths of all modules in the project." } } }, @@ -73,8 +73,8 @@ "name": "RendererConfig", "kind": "class", "path": "docforge.renderers.base.RendererConfig", - "signature": "", - "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.", + "signature": "", + "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: Directory where generated documentation files will be written.\n project: Documentation project model to be rendered.", "members": { "out_dir": { "name": "out_dir", @@ -96,8 +96,8 @@ "name": "DocRenderer", "kind": "class", "path": "docforge.renderers.base.DocRenderer", - "signature": "", - "docstring": "Protocol defining the interface for documentation renderers.", + "signature": "", + "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.", "members": { "name": { "name": "name", @@ -110,8 +110,8 @@ "name": "generate_sources", "kind": "function", "path": "docforge.renderers.base.DocRenderer.generate_sources", - "signature": "", - "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." + "signature": "", + "docstring": "Generate renderer-specific documentation sources.\n\nArgs:\n project: Project model containing modules and documentation objects.\n out_dir: Directory where generated documentation sources\n should be written." } } } diff --git a/mcp_docs/modules/docforge.renderers.json b/mcp_docs/modules/docforge.renderers.json index 81a0102..3c0f6c6 100644 --- a/mcp_docs/modules/docforge.renderers.json +++ b/mcp_docs/modules/docforge.renderers.json @@ -2,14 +2,14 @@ "module": "docforge.renderers", "content": { "path": "docforge.renderers", - "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`.", + "docstring": "Renderers layer for doc-forge.\n\nThe ``docforge.renderers`` package transforms the internal documentation\nmodels into files formatted for specific documentation systems.\n\n---\n\nOverview\n--------\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\nExtending\n---------\n\nNew renderers can be added by implementing the ``DocRenderer`` protocol\ndefined in ``docforge.renderers.base``.\n\n---", "objects": { "MkDocsRenderer": { "name": "MkDocsRenderer", "kind": "class", "path": "docforge.renderers.MkDocsRenderer", "signature": "", - "docstring": "Renderer that generates Markdown source files formatted for the MkDocs\n'mkdocstrings' plugin.", + "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", @@ -23,7 +23,14 @@ "kind": "function", "path": "docforge.renderers.MkDocsRenderer.generate_sources", "signature": "", - "docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project: The project models to render.\n out_dir: Target directory for documentation files.\n module_is_source: Module is the source folder and to be treated as the root folder." + "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 model containing modules to document.\n out_dir: Directory where generated Markdown files will be written.\n module_is_source: If True, treat the specified module as the\n documentation root rather than nesting it inside a folder." + }, + "generate_readme": { + "name": "generate_readme", + "kind": "function", + "path": "docforge.renderers.MkDocsRenderer.generate_readme", + "signature": "", + "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\n project root directory.\n- If False, README generation is currently not implemented.\n\nArgs:\n project: Project model containing documentation metadata.\n docs_dir: Directory containing generated documentation sources.\n module_is_source: Whether the module is treated as the project\n source root." } } }, @@ -32,7 +39,7 @@ "kind": "class", "path": "docforge.renderers.MCPRenderer", "signature": "", - "docstring": "Renderer that emits MCP-native JSON resources from docforge models.", + "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).", "members": { "name": { "name": "name", @@ -46,7 +53,7 @@ "kind": "function", "path": "docforge.renderers.MCPRenderer.generate_sources", "signature": "", - "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." + "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: Documentation project model to render.\n out_dir: Directory where MCP resources will be written." } } }, @@ -55,7 +62,7 @@ "kind": "module", "path": "docforge.renderers.base", "signature": null, - "docstring": "This module defines the base interfaces and configuration containers for\ndoc-forge renderers. All renderer implementations should adhere to the\nDocRenderer protocol.", + "docstring": "Renderer 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.", "members": { "Path": { "name": "Path", @@ -76,7 +83,7 @@ "kind": "class", "path": "docforge.renderers.base.Project", "signature": "", - "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.", + "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: Name of the project.\n modules: Mapping of module paths to ``Module`` instances.", "members": { "name": { "name": "name", @@ -97,28 +104,28 @@ "kind": "function", "path": "docforge.renderers.base.Project.add_module", "signature": "", - "docstring": "Add a module to the project.\n\nArgs:\n module: The module to add." + "docstring": "Register a module in the project.\n\nArgs:\n module: Module instance to add to the project." }, "get_module": { "name": "get_module", "kind": "function", "path": "docforge.renderers.base.Project.get_module", "signature": "", - "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." + "docstring": "Retrieve a module by its dotted path.\n\nArgs:\n path: Fully qualified dotted module path (for example ``pkg.module``).\n\nReturns:\n The corresponding ``Module`` instance.\n\nRaises:\n KeyError: If the module does not exist in the project." }, "get_all_modules": { "name": "get_all_modules", "kind": "function", "path": "docforge.renderers.base.Project.get_all_modules", "signature": "", - "docstring": "Get all modules in the project.\n\nReturns:\n An iterable of Module objects." + "docstring": "Return all modules contained in the project.\n\nReturns:\n An iterable of ``Module`` instances." }, "get_module_list": { "name": "get_module_list", "kind": "function", "path": "docforge.renderers.base.Project.get_module_list", "signature": "", - "docstring": "Get the list of all module dotted paths.\n\nReturns:\n A list of module paths." + "docstring": "Return the list of module import paths.\n\nReturns:\n A list containing the dotted paths of all modules in the project." } } }, @@ -126,8 +133,8 @@ "name": "RendererConfig", "kind": "class", "path": "docforge.renderers.base.RendererConfig", - "signature": "", - "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.", + "signature": "", + "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: Directory where generated documentation files will be written.\n project: Documentation project model to be rendered.", "members": { "out_dir": { "name": "out_dir", @@ -149,8 +156,8 @@ "name": "DocRenderer", "kind": "class", "path": "docforge.renderers.base.DocRenderer", - "signature": "", - "docstring": "Protocol defining the interface for documentation renderers.", + "signature": "", + "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.", "members": { "name": { "name": "name", @@ -163,8 +170,8 @@ "name": "generate_sources", "kind": "function", "path": "docforge.renderers.base.DocRenderer.generate_sources", - "signature": "", - "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." + "signature": "", + "docstring": "Generate renderer-specific documentation sources.\n\nArgs:\n project: Project model containing modules and documentation objects.\n out_dir: Directory where generated documentation sources\n should be written." } } } @@ -210,7 +217,7 @@ "kind": "class", "path": "docforge.renderers.mcp_renderer.Project", "signature": "", - "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.", + "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: Name of the project.\n modules: Mapping of module paths to ``Module`` instances.", "members": { "name": { "name": "name", @@ -231,28 +238,28 @@ "kind": "function", "path": "docforge.renderers.mcp_renderer.Project.add_module", "signature": "", - "docstring": "Add a module to the project.\n\nArgs:\n module: The module to add." + "docstring": "Register a module in the project.\n\nArgs:\n module: Module instance to add to the project." }, "get_module": { "name": "get_module", "kind": "function", "path": "docforge.renderers.mcp_renderer.Project.get_module", "signature": "", - "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." + "docstring": "Retrieve a module by its dotted path.\n\nArgs:\n path: Fully qualified dotted module path (for example ``pkg.module``).\n\nReturns:\n The corresponding ``Module`` instance.\n\nRaises:\n KeyError: If the module does not exist in the project." }, "get_all_modules": { "name": "get_all_modules", "kind": "function", "path": "docforge.renderers.mcp_renderer.Project.get_all_modules", "signature": "", - "docstring": "Get all modules in the project.\n\nReturns:\n An iterable of Module objects." + "docstring": "Return all modules contained in the project.\n\nReturns:\n An iterable of ``Module`` instances." }, "get_module_list": { "name": "get_module_list", "kind": "function", "path": "docforge.renderers.mcp_renderer.Project.get_module_list", "signature": "", - "docstring": "Get the list of all module dotted paths.\n\nReturns:\n A list of module paths." + "docstring": "Return the list of module import paths.\n\nReturns:\n A list containing the dotted paths of all modules in the project." } } }, @@ -261,7 +268,7 @@ "kind": "class", "path": "docforge.renderers.mcp_renderer.Module", "signature": "", - "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.", + "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: Dotted import path of the module.\n docstring: Module-level documentation string, if present.\n members: Mapping of object names to their corresponding\n ``DocObject`` representations.", "members": { "path": { "name": "path", @@ -289,21 +296,21 @@ "kind": "function", "path": "docforge.renderers.mcp_renderer.Module.add_object", "signature": "", - "docstring": "Add a documented object to the module.\n\nArgs:\n obj: The object to add." + "docstring": "Add a documented object to the module.\n\nArgs:\n obj: Documentation object to register as a top-level\n member of the module." }, "get_object": { "name": "get_object", "kind": "function", "path": "docforge.renderers.mcp_renderer.Module.get_object", "signature": "", - "docstring": "Retrieve a member object by name.\n\nArgs:\n name: The name of the object.\n\nReturns:\n The requested DocObject." + "docstring": "Retrieve a documented object by name.\n\nArgs:\n name: Name of the object to retrieve.\n\nReturns:\n The corresponding ``DocObject`` instance.\n\nRaises:\n KeyError: If no object with the given name exists." }, "get_all_objects": { "name": "get_all_objects", "kind": "function", "path": "docforge.renderers.mcp_renderer.Module.get_all_objects", "signature": "", - "docstring": "Get all top-level objects in the module.\n\nReturns:\n An iterable of DocObject instances." + "docstring": "Return all top-level documentation objects in the module.\n\nReturns:\n An iterable of ``DocObject`` instances representing the\n module's public members." } } }, @@ -312,7 +319,7 @@ "kind": "class", "path": "docforge.renderers.mcp_renderer.DocObject", "signature": "", - "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.", + "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: Local name of the object.\n kind: Type of object (for example ``class``, ``function``,\n ``method``, or ``attribute``).\n path: Fully qualified dotted path to the object.\n signature: Callable signature if the object represents a callable.\n docstring: Raw docstring text extracted from the source code.\n members: Mapping of member names to child ``DocObject`` instances.", "members": { "name": { "name": "name", @@ -361,21 +368,21 @@ "kind": "function", "path": "docforge.renderers.mcp_renderer.DocObject.add_member", "signature": "", - "docstring": "Add a child member to this object (e.g., a method to a class).\n\nArgs:\n obj: The child DocObject to add." + "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." }, "get_member": { "name": "get_member", "kind": "function", "path": "docforge.renderers.mcp_renderer.DocObject.get_member", "signature": "", - "docstring": "Retrieve a child member by name.\n\nArgs:\n name: The name of the member.\n\nReturns:\n The requested DocObject." + "docstring": "Retrieve a member object by name.\n\nArgs:\n name: Name of the member to retrieve.\n\nReturns:\n The corresponding ``DocObject`` instance.\n\nRaises:\n KeyError: If the member does not exist." }, "get_all_members": { "name": "get_all_members", "kind": "function", "path": "docforge.renderers.mcp_renderer.DocObject.get_all_members", "signature": "", - "docstring": "Get all members of this object.\n\nReturns:\n An iterable of child DocObject instances." + "docstring": "Return all child members of the object.\n\nReturns:\n An iterable of ``DocObject`` instances representing nested members." } } }, @@ -383,8 +390,8 @@ "name": "MCPRenderer", "kind": "class", "path": "docforge.renderers.mcp_renderer.MCPRenderer", - "signature": "", - "docstring": "Renderer that emits MCP-native JSON resources from docforge models.", + "signature": "", + "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).", "members": { "name": { "name": "name", @@ -397,8 +404,8 @@ "name": "generate_sources", "kind": "function", "path": "docforge.renderers.mcp_renderer.MCPRenderer.generate_sources", - "signature": "", - "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." + "signature": "", + "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: Documentation project model to render.\n out_dir: Directory where MCP resources will be written." } } } @@ -409,7 +416,7 @@ "kind": "module", "path": "docforge.renderers.mkdocs_renderer", "signature": null, - "docstring": "MkDocsRenderer\n\nGenerates Markdown source files compatible with MkDocs Material\nand mkdocstrings, ensuring:\n\n- Root index.md always exists\n- Parent package indexes are created automatically\n- Child modules are linked in parent index files", + "docstring": "MkDocs 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", "members": { "Path": { "name": "Path", @@ -423,7 +430,7 @@ "kind": "class", "path": "docforge.renderers.mkdocs_renderer.Project", "signature": "", - "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.", + "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: Name of the project.\n modules: Mapping of module paths to ``Module`` instances.", "members": { "name": { "name": "name", @@ -444,28 +451,28 @@ "kind": "function", "path": "docforge.renderers.mkdocs_renderer.Project.add_module", "signature": "", - "docstring": "Add a module to the project.\n\nArgs:\n module: The module to add." + "docstring": "Register a module in the project.\n\nArgs:\n module: Module instance to add to the project." }, "get_module": { "name": "get_module", "kind": "function", "path": "docforge.renderers.mkdocs_renderer.Project.get_module", "signature": "", - "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." + "docstring": "Retrieve a module by its dotted path.\n\nArgs:\n path: Fully qualified dotted module path (for example ``pkg.module``).\n\nReturns:\n The corresponding ``Module`` instance.\n\nRaises:\n KeyError: If the module does not exist in the project." }, "get_all_modules": { "name": "get_all_modules", "kind": "function", "path": "docforge.renderers.mkdocs_renderer.Project.get_all_modules", "signature": "", - "docstring": "Get all modules in the project.\n\nReturns:\n An iterable of Module objects." + "docstring": "Return all modules contained in the project.\n\nReturns:\n An iterable of ``Module`` instances." }, "get_module_list": { "name": "get_module_list", "kind": "function", "path": "docforge.renderers.mkdocs_renderer.Project.get_module_list", "signature": "", - "docstring": "Get the list of all module dotted paths.\n\nReturns:\n A list of module paths." + "docstring": "Return the list of module import paths.\n\nReturns:\n A list containing the dotted paths of all modules in the project." } } }, @@ -474,7 +481,7 @@ "kind": "class", "path": "docforge.renderers.mkdocs_renderer.Module", "signature": "", - "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.", + "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: Dotted import path of the module.\n docstring: Module-level documentation string, if present.\n members: Mapping of object names to their corresponding\n ``DocObject`` representations.", "members": { "path": { "name": "path", @@ -502,21 +509,21 @@ "kind": "function", "path": "docforge.renderers.mkdocs_renderer.Module.add_object", "signature": "", - "docstring": "Add a documented object to the module.\n\nArgs:\n obj: The object to add." + "docstring": "Add a documented object to the module.\n\nArgs:\n obj: Documentation object to register as a top-level\n member of the module." }, "get_object": { "name": "get_object", "kind": "function", "path": "docforge.renderers.mkdocs_renderer.Module.get_object", "signature": "", - "docstring": "Retrieve a member object by name.\n\nArgs:\n name: The name of the object.\n\nReturns:\n The requested DocObject." + "docstring": "Retrieve a documented object by name.\n\nArgs:\n name: Name of the object to retrieve.\n\nReturns:\n The corresponding ``DocObject`` instance.\n\nRaises:\n KeyError: If no object with the given name exists." }, "get_all_objects": { "name": "get_all_objects", "kind": "function", "path": "docforge.renderers.mkdocs_renderer.Module.get_all_objects", "signature": "", - "docstring": "Get all top-level objects in the module.\n\nReturns:\n An iterable of DocObject instances." + "docstring": "Return all top-level documentation objects in the module.\n\nReturns:\n An iterable of ``DocObject`` instances representing the\n module's public members." } } }, @@ -524,8 +531,8 @@ "name": "MkDocsRenderer", "kind": "class", "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer", - "signature": "", - "docstring": "Renderer that generates Markdown source files formatted for the MkDocs\n'mkdocstrings' plugin.", + "signature": "", + "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", @@ -538,8 +545,15 @@ "name": "generate_sources", "kind": "function", "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources", - "signature": "", - "docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project: The project models to render.\n out_dir: Target directory for documentation files.\n module_is_source: Module is the source folder and to be treated as the root folder." + "signature": "", + "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 model containing modules to document.\n out_dir: Directory where generated Markdown files will be written.\n module_is_source: If True, treat the specified module as the\n documentation root rather than nesting it inside a folder." + }, + "generate_readme": { + "name": "generate_readme", + "kind": "function", + "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_readme", + "signature": "", + "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\n project root directory.\n- If False, README generation is currently not implemented.\n\nArgs:\n project: Project model containing documentation metadata.\n docs_dir: Directory containing generated documentation sources.\n module_is_source: Whether the module is treated as the project\n source root." } } } diff --git a/mcp_docs/modules/docforge.renderers.mcp_renderer.json b/mcp_docs/modules/docforge.renderers.mcp_renderer.json index 0bcfd11..c1cfd76 100644 --- a/mcp_docs/modules/docforge.renderers.mcp_renderer.json +++ b/mcp_docs/modules/docforge.renderers.mcp_renderer.json @@ -37,7 +37,7 @@ "kind": "class", "path": "docforge.renderers.mcp_renderer.Project", "signature": "", - "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.", + "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: Name of the project.\n modules: Mapping of module paths to ``Module`` instances.", "members": { "name": { "name": "name", @@ -58,28 +58,28 @@ "kind": "function", "path": "docforge.renderers.mcp_renderer.Project.add_module", "signature": "", - "docstring": "Add a module to the project.\n\nArgs:\n module: The module to add." + "docstring": "Register a module in the project.\n\nArgs:\n module: Module instance to add to the project." }, "get_module": { "name": "get_module", "kind": "function", "path": "docforge.renderers.mcp_renderer.Project.get_module", "signature": "", - "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." + "docstring": "Retrieve a module by its dotted path.\n\nArgs:\n path: Fully qualified dotted module path (for example ``pkg.module``).\n\nReturns:\n The corresponding ``Module`` instance.\n\nRaises:\n KeyError: If the module does not exist in the project." }, "get_all_modules": { "name": "get_all_modules", "kind": "function", "path": "docforge.renderers.mcp_renderer.Project.get_all_modules", "signature": "", - "docstring": "Get all modules in the project.\n\nReturns:\n An iterable of Module objects." + "docstring": "Return all modules contained in the project.\n\nReturns:\n An iterable of ``Module`` instances." }, "get_module_list": { "name": "get_module_list", "kind": "function", "path": "docforge.renderers.mcp_renderer.Project.get_module_list", "signature": "", - "docstring": "Get the list of all module dotted paths.\n\nReturns:\n A list of module paths." + "docstring": "Return the list of module import paths.\n\nReturns:\n A list containing the dotted paths of all modules in the project." } } }, @@ -88,7 +88,7 @@ "kind": "class", "path": "docforge.renderers.mcp_renderer.Module", "signature": "", - "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.", + "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: Dotted import path of the module.\n docstring: Module-level documentation string, if present.\n members: Mapping of object names to their corresponding\n ``DocObject`` representations.", "members": { "path": { "name": "path", @@ -116,21 +116,21 @@ "kind": "function", "path": "docforge.renderers.mcp_renderer.Module.add_object", "signature": "", - "docstring": "Add a documented object to the module.\n\nArgs:\n obj: The object to add." + "docstring": "Add a documented object to the module.\n\nArgs:\n obj: Documentation object to register as a top-level\n member of the module." }, "get_object": { "name": "get_object", "kind": "function", "path": "docforge.renderers.mcp_renderer.Module.get_object", "signature": "", - "docstring": "Retrieve a member object by name.\n\nArgs:\n name: The name of the object.\n\nReturns:\n The requested DocObject." + "docstring": "Retrieve a documented object by name.\n\nArgs:\n name: Name of the object to retrieve.\n\nReturns:\n The corresponding ``DocObject`` instance.\n\nRaises:\n KeyError: If no object with the given name exists." }, "get_all_objects": { "name": "get_all_objects", "kind": "function", "path": "docforge.renderers.mcp_renderer.Module.get_all_objects", "signature": "", - "docstring": "Get all top-level objects in the module.\n\nReturns:\n An iterable of DocObject instances." + "docstring": "Return all top-level documentation objects in the module.\n\nReturns:\n An iterable of ``DocObject`` instances representing the\n module's public members." } } }, @@ -139,7 +139,7 @@ "kind": "class", "path": "docforge.renderers.mcp_renderer.DocObject", "signature": "", - "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.", + "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: Local name of the object.\n kind: Type of object (for example ``class``, ``function``,\n ``method``, or ``attribute``).\n path: Fully qualified dotted path to the object.\n signature: Callable signature if the object represents a callable.\n docstring: Raw docstring text extracted from the source code.\n members: Mapping of member names to child ``DocObject`` instances.", "members": { "name": { "name": "name", @@ -188,21 +188,21 @@ "kind": "function", "path": "docforge.renderers.mcp_renderer.DocObject.add_member", "signature": "", - "docstring": "Add a child member to this object (e.g., a method to a class).\n\nArgs:\n obj: The child DocObject to add." + "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." }, "get_member": { "name": "get_member", "kind": "function", "path": "docforge.renderers.mcp_renderer.DocObject.get_member", "signature": "", - "docstring": "Retrieve a child member by name.\n\nArgs:\n name: The name of the member.\n\nReturns:\n The requested DocObject." + "docstring": "Retrieve a member object by name.\n\nArgs:\n name: Name of the member to retrieve.\n\nReturns:\n The corresponding ``DocObject`` instance.\n\nRaises:\n KeyError: If the member does not exist." }, "get_all_members": { "name": "get_all_members", "kind": "function", "path": "docforge.renderers.mcp_renderer.DocObject.get_all_members", "signature": "", - "docstring": "Get all members of this object.\n\nReturns:\n An iterable of child DocObject instances." + "docstring": "Return all child members of the object.\n\nReturns:\n An iterable of ``DocObject`` instances representing nested members." } } }, @@ -210,8 +210,8 @@ "name": "MCPRenderer", "kind": "class", "path": "docforge.renderers.mcp_renderer.MCPRenderer", - "signature": "", - "docstring": "Renderer that emits MCP-native JSON resources from docforge models.", + "signature": "", + "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).", "members": { "name": { "name": "name", @@ -224,8 +224,8 @@ "name": "generate_sources", "kind": "function", "path": "docforge.renderers.mcp_renderer.MCPRenderer.generate_sources", - "signature": "", - "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." + "signature": "", + "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: Documentation project model to render.\n out_dir: Directory where MCP resources will be written." } } } diff --git a/mcp_docs/modules/docforge.renderers.mkdocs_renderer.json b/mcp_docs/modules/docforge.renderers.mkdocs_renderer.json index 73ce76c..dbb08e0 100644 --- a/mcp_docs/modules/docforge.renderers.mkdocs_renderer.json +++ b/mcp_docs/modules/docforge.renderers.mkdocs_renderer.json @@ -2,7 +2,7 @@ "module": "docforge.renderers.mkdocs_renderer", "content": { "path": "docforge.renderers.mkdocs_renderer", - "docstring": "MkDocsRenderer\n\nGenerates Markdown source files compatible with MkDocs Material\nand mkdocstrings, ensuring:\n\n- Root index.md always exists\n- Parent package indexes are created automatically\n- Child modules are linked in parent index files", + "docstring": "MkDocs 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", "objects": { "Path": { "name": "Path", @@ -16,7 +16,7 @@ "kind": "class", "path": "docforge.renderers.mkdocs_renderer.Project", "signature": "", - "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.", + "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: Name of the project.\n modules: Mapping of module paths to ``Module`` instances.", "members": { "name": { "name": "name", @@ -37,28 +37,28 @@ "kind": "function", "path": "docforge.renderers.mkdocs_renderer.Project.add_module", "signature": "", - "docstring": "Add a module to the project.\n\nArgs:\n module: The module to add." + "docstring": "Register a module in the project.\n\nArgs:\n module: Module instance to add to the project." }, "get_module": { "name": "get_module", "kind": "function", "path": "docforge.renderers.mkdocs_renderer.Project.get_module", "signature": "", - "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." + "docstring": "Retrieve a module by its dotted path.\n\nArgs:\n path: Fully qualified dotted module path (for example ``pkg.module``).\n\nReturns:\n The corresponding ``Module`` instance.\n\nRaises:\n KeyError: If the module does not exist in the project." }, "get_all_modules": { "name": "get_all_modules", "kind": "function", "path": "docforge.renderers.mkdocs_renderer.Project.get_all_modules", "signature": "", - "docstring": "Get all modules in the project.\n\nReturns:\n An iterable of Module objects." + "docstring": "Return all modules contained in the project.\n\nReturns:\n An iterable of ``Module`` instances." }, "get_module_list": { "name": "get_module_list", "kind": "function", "path": "docforge.renderers.mkdocs_renderer.Project.get_module_list", "signature": "", - "docstring": "Get the list of all module dotted paths.\n\nReturns:\n A list of module paths." + "docstring": "Return the list of module import paths.\n\nReturns:\n A list containing the dotted paths of all modules in the project." } } }, @@ -67,7 +67,7 @@ "kind": "class", "path": "docforge.renderers.mkdocs_renderer.Module", "signature": "", - "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.", + "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: Dotted import path of the module.\n docstring: Module-level documentation string, if present.\n members: Mapping of object names to their corresponding\n ``DocObject`` representations.", "members": { "path": { "name": "path", @@ -95,21 +95,21 @@ "kind": "function", "path": "docforge.renderers.mkdocs_renderer.Module.add_object", "signature": "", - "docstring": "Add a documented object to the module.\n\nArgs:\n obj: The object to add." + "docstring": "Add a documented object to the module.\n\nArgs:\n obj: Documentation object to register as a top-level\n member of the module." }, "get_object": { "name": "get_object", "kind": "function", "path": "docforge.renderers.mkdocs_renderer.Module.get_object", "signature": "", - "docstring": "Retrieve a member object by name.\n\nArgs:\n name: The name of the object.\n\nReturns:\n The requested DocObject." + "docstring": "Retrieve a documented object by name.\n\nArgs:\n name: Name of the object to retrieve.\n\nReturns:\n The corresponding ``DocObject`` instance.\n\nRaises:\n KeyError: If no object with the given name exists." }, "get_all_objects": { "name": "get_all_objects", "kind": "function", "path": "docforge.renderers.mkdocs_renderer.Module.get_all_objects", "signature": "", - "docstring": "Get all top-level objects in the module.\n\nReturns:\n An iterable of DocObject instances." + "docstring": "Return all top-level documentation objects in the module.\n\nReturns:\n An iterable of ``DocObject`` instances representing the\n module's public members." } } }, @@ -117,8 +117,8 @@ "name": "MkDocsRenderer", "kind": "class", "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer", - "signature": "", - "docstring": "Renderer that generates Markdown source files formatted for the MkDocs\n'mkdocstrings' plugin.", + "signature": "", + "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", @@ -131,8 +131,15 @@ "name": "generate_sources", "kind": "function", "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources", - "signature": "", - "docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project: The project models to render.\n out_dir: Target directory for documentation files.\n module_is_source: Module is the source folder and to be treated as the root folder." + "signature": "", + "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 model containing modules to document.\n out_dir: Directory where generated Markdown files will be written.\n module_is_source: If True, treat the specified module as the\n documentation root rather than nesting it inside a folder." + }, + "generate_readme": { + "name": "generate_readme", + "kind": "function", + "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_readme", + "signature": "", + "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\n project root directory.\n- If False, README generation is currently not implemented.\n\nArgs:\n project: Project model containing documentation metadata.\n docs_dir: Directory containing generated documentation sources.\n module_is_source: Whether the module is treated as the project\n source root." } } } diff --git a/mcp_docs/modules/docforge.servers.json b/mcp_docs/modules/docforge.servers.json index cdf9e81..6e31ead 100644 --- a/mcp_docs/modules/docforge.servers.json +++ b/mcp_docs/modules/docforge.servers.json @@ -2,14 +2,14 @@ "module": "docforge.servers", "content": { "path": "docforge.servers", - "docstring": null, + "docstring": "Server 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---", "objects": { "MCPServer": { "name": "MCPServer", "kind": "class", "path": "docforge.servers.MCPServer", "signature": "", - "docstring": "MCP server for serving a pre-built MCP documentation bundle.", + "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.", "members": { "mcp_root": { "name": "mcp_root", @@ -30,7 +30,7 @@ "kind": "function", "path": "docforge.servers.MCPServer.run", "signature": "", - "docstring": "Start the MCP server.\n\nArgs:\n transport: MCP transport (default: streamable-http)" + "docstring": "Start the MCP server.\n\nArgs:\n transport: Transport mechanism used by the MCP server. Supported\n options include ``stdio``, ``sse``, and ``streamable-http``." } } }, @@ -87,8 +87,8 @@ "name": "MCPServer", "kind": "class", "path": "docforge.servers.mcp_server.MCPServer", - "signature": "", - "docstring": "MCP server for serving a pre-built MCP documentation bundle.", + "signature": "", + "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.", "members": { "mcp_root": { "name": "mcp_root", @@ -108,8 +108,8 @@ "name": "run", "kind": "function", "path": "docforge.servers.mcp_server.MCPServer.run", - "signature": "", - "docstring": "Start the MCP server.\n\nArgs:\n transport: MCP transport (default: streamable-http)" + "signature": "", + "docstring": "Start the MCP server.\n\nArgs:\n transport: Transport mechanism used by the MCP server. Supported\n options include ``stdio``, ``sse``, and ``streamable-http``." } } } diff --git a/mcp_docs/modules/docforge.servers.mcp_server.json b/mcp_docs/modules/docforge.servers.mcp_server.json index 8ab31cc..e4ec8d2 100644 --- a/mcp_docs/modules/docforge.servers.mcp_server.json +++ b/mcp_docs/modules/docforge.servers.mcp_server.json @@ -50,8 +50,8 @@ "name": "MCPServer", "kind": "class", "path": "docforge.servers.mcp_server.MCPServer", - "signature": "", - "docstring": "MCP server for serving a pre-built MCP documentation bundle.", + "signature": "", + "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.", "members": { "mcp_root": { "name": "mcp_root", @@ -71,8 +71,8 @@ "name": "run", "kind": "function", "path": "docforge.servers.mcp_server.MCPServer.run", - "signature": "", - "docstring": "Start the MCP server.\n\nArgs:\n transport: MCP transport (default: streamable-http)" + "signature": "", + "docstring": "Start the MCP server.\n\nArgs:\n transport: Transport mechanism used by the MCP server. Supported\n options include ``stdio``, ``sse``, and ``streamable-http``." } } } diff --git a/mkdocs.yml b/mkdocs.yml index 629d62c..9fc5e49 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -8,12 +8,19 @@ theme: text: Inter code: JetBrains Mono features: - - navigation.tabs + - navigation.sections - navigation.expand - navigation.top - navigation.instant + - navigation.tracking + - navigation.indexes - content.code.copy - content.code.annotate + - content.tabs.link + - content.action.edit + - search.highlight + - search.share + - search.suggest plugins: - search - mkdocstrings: @@ -31,10 +38,30 @@ plugins: annotations_path: brief show_root_heading: 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: - Home: index.md diff --git a/tests/renderers/mkdocs/test_mkdocs_content.py b/tests/renderers/mkdocs/test_mkdocs_content.py index afc3f47..80cee04 100644 --- a/tests/renderers/mkdocs/test_mkdocs_content.py +++ b/tests/renderers/mkdocs/test_mkdocs_content.py @@ -17,3 +17,34 @@ def test_mkdocs_file_content(tmp_path: Path): assert "# 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 \ No newline at end of file diff --git a/tests/renderers/mkdocs/test_mkdocs_idempotency.py b/tests/renderers/mkdocs/test_mkdocs_idempotency.py index 0cdfdb2..f894665 100644 --- a/tests/renderers/mkdocs/test_mkdocs_idempotency.py +++ b/tests/renderers/mkdocs/test_mkdocs_idempotency.py @@ -18,3 +18,36 @@ def test_mkdocs_idempotent(tmp_path: Path): second = (out_dir / "testpkg" / "mod.md").read_text() 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 \ No newline at end of file diff --git a/tests/renderers/mkdocs/test_mkdocs_module_coverage.py b/tests/renderers/mkdocs/test_mkdocs_module_coverage.py index ba054bf..835096e 100644 --- a/tests/renderers/mkdocs/test_mkdocs_module_coverage.py +++ b/tests/renderers/mkdocs/test_mkdocs_module_coverage.py @@ -17,6 +17,12 @@ def test_mkdocs_emits_all_modules(tmp_path: Path) -> None: renderer = MkDocsRenderer() renderer.generate_sources(project, tmp_path) + renderer.generate_readme( + project, + tmp_path, + module_is_source=True, + ) + emitted = { p.relative_to(tmp_path).as_posix() for p in tmp_path.rglob("*.md") @@ -39,3 +45,8 @@ def test_mkdocs_emits_all_modules(tmp_path: Path) -> None: missing = expected - emitted 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 diff --git a/tests/renderers/mkdocs/test_mkdocs_structure.py b/tests/renderers/mkdocs/test_mkdocs_structure.py index 1fd6170..4c6788f 100644 --- a/tests/renderers/mkdocs/test_mkdocs_structure.py +++ b/tests/renderers/mkdocs/test_mkdocs_structure.py @@ -13,6 +13,12 @@ def test_mkdocs_directory_structure(tmp_path: Path): renderer = MkDocsRenderer() 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" / "sub.md").exists() + assert (tmp_path / "README.md").exists()