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