Skip to content

# 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

    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`