Mkdocs Renderer

docforge.renderers.mkdocs_renderer

Summary

MkDocs renderer implementation.

This module defines the MkDocsRenderer class, which generates Markdown documentation sources compatible with MkDocs Material and the mkdocstrings plugin.

The renderer ensures a consistent documentation structure by:

• Creating a root index.md if one does not exist
• Generating package index pages automatically
• Linking child modules within parent package pages
• Optionally generating README.md from the root package docstring

Classes

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

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

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