Skip to content

# Renderers

## `` docforge.renderers

### Summary

Renderers layer for doc-forge.

The `docforge.renderers` package transforms the internal documentation models into files formatted for specific documentation systems.

### Overview

Renderers consume the doc-forge project model and generate output suitable for documentation tools or machine interfaces.

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`.

### Classes

#### `` MCPRenderer

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).

##### Functions

###### `` generate_sources

    1

    generate_sources(project: Project, out_dir: Path) -> None

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`.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`project` | `Project` | Documentation project model to render. | required
`out_dir` | `Path` | Directory where MCP resources will be written. | required

#### `` MkDocsRenderer

Renderer that produces Markdown documentation for MkDocs.

Generated pages use mkdocstrings directives to reference Python modules, allowing MkDocs to render API documentation dynamically.

##### Functions

###### `` generate_readme

    1

    generate_readme(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.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`project` | `Project` | Project model containing documentation metadata. | required
`docs_dir` | `Path` | Directory containing generated documentation sources. | required
`module_is_source` | `bool` | Whether the module is treated as the project source root. | `None`

###### `` generate_sources

    1

    generate_sources(project: Project, out_dir: Path, module_is_source: bool | None = None) -> None

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.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`project` | `Project` | Project model containing modules to document. | required
`out_dir` | `Path` | Directory where generated Markdown files will be written. | required
`module_is_source` | `bool` | If True, treat the specified module as the documentation root rather than nesting it inside a folder. | `None`