aetos/doc-forge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

updated docs strings and added README.md

Browse Source
This commit is contained in:
Vishesh 'ironeagle' Bangotra
2026-03-08 17:59:55 +05:30
parent e8e16f3996
commit 8253c25928
37 changed files with 1091 additions and 834 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
docforge/renderers/__init__.py
View File

@@ -1,13 +1,14 @@
"""
# Summary
Renderers layer for doc-forge.
The ``docforge.renderers`` package transforms the internal documentation
The `docforge.renderers` package transforms the internal documentation
models into files formatted for specific documentation systems.
---
Overview
--------
# Overview
Renderers consume the doc-forge project model and generate output suitable
for documentation tools or machine interfaces.
@@ -15,18 +16,17 @@ 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.
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
---------
# Extending
New renderers can be added by implementing the ``DocRenderer`` protocol
defined in ``docforge.renderers.base``.
New renderers can be added by implementing the `DocRenderer` protocol
defined in `docforge.renderers.base`.
---
"""

30
docforge/renderers/base.py
View File

@@ -1,9 +1,11 @@
"""
# Summary
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.
`DocRenderer` protocol.
"""
from pathlib import Path
@@ -16,12 +18,15 @@ class RendererConfig:
"""
Configuration container for documentation renderers.
A ``RendererConfig`` instance groups together the project model and the
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.
out_dir (Path):
Directory where generated documentation files will be written.
project (Project):
Documentation project model to be rendered.
"""
def __init__(self, out_dir: Path, project: Project) -> None:
@@ -29,8 +34,11 @@ class RendererConfig:
Initialize a RendererConfig instance.
Args:
out_dir: Target directory where documentation files should be written.
project: Introspected project model to render.
out_dir (Path):
Target directory where documentation files should be written.
project (Project):
Introspected project model to render.
"""
self.out_dir = out_dir
self.project = project
@@ -41,7 +49,7 @@ 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.
`Project` model into renderer-specific documentation sources.
"""
name: str
@@ -55,8 +63,10 @@ class DocRenderer(Protocol):
Generate renderer-specific documentation sources.
Args:
project: Project model containing modules and documentation objects.
out_dir: Directory where generated documentation sources
should be written.
project (Project):
Project model containing modules and documentation objects.
out_dir (Path):
Directory where generated documentation sources should be written.
"""
...

43
docforge/renderers/mcp_renderer.py
View File

@@ -1,3 +1,12 @@
"""
# Summary
MCP renderer implementation.
This module defines the `MCPRenderer` class, which generates documentation
resources compatible with the Model Context Protocol (MCP).
"""
import json
from pathlib import Path
from typing import Dict, List
@@ -21,11 +30,14 @@ class MCPRenderer:
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``.
supporting metadata files such as `nav.json` and `index.json`.
Args:
project: Documentation project model to render.
out_dir: Directory where MCP resources will be written.
project (Project):
Documentation project model to render.
out_dir (Path):
Directory where MCP resources will be written.
"""
modules_dir = out_dir / "modules"
modules_dir.mkdir(parents=True, exist_ok=True)
@@ -64,8 +76,11 @@ class MCPRenderer:
Serialize a module into an MCP resource file.
Args:
module: Module instance to serialize.
modules_dir: Directory where module JSON files are stored.
module (Module):
Module instance to serialize.
modules_dir (Path):
Directory where module JSON files are stored.
"""
payload = {
"module": module.path,
@@ -81,10 +96,12 @@ class MCPRenderer:
Convert a Module model into MCP-compatible structured data.
Args:
module: Module instance to convert.
module (Module):
Module instance to convert.
Returns:
Dictionary representing the module and its documented objects.
Dict:
Dictionary representing the module and its documented objects.
"""
data: Dict = {
"path": module.path,
@@ -102,10 +119,12 @@ class MCPRenderer:
Recursively convert a DocObject into structured MCP data.
Args:
obj: Documentation object to convert.
obj (DocObject):
Documentation object to convert.
Returns:
Dictionary describing the object and any nested members.
Dict:
Dictionary describing the object and any nested members.
"""
data: Dict = {
"name": obj.name,
@@ -130,9 +149,11 @@ class MCPRenderer:
Serialize data to formatted JSON.
Args:
data: Dictionary to serialize.
data (Dict):
Dictionary to serialize.
Returns:
JSON string formatted with indentation and UTF-8 compatibility.
str:
JSON string formatted with indentation and UTF-8 compatibility.
"""
return json.dumps(data, indent=2, ensure_ascii=False)

97
docforge/renderers/mkdocs_renderer.py
View File

@@ -1,16 +1,18 @@
"""
# Summary
MkDocs renderer implementation.
This module defines the ``MkDocsRenderer`` class, which generates Markdown
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
- 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
- Optionally generating `README.md` from the root package docstring
"""
from pathlib import Path
@@ -45,10 +47,15 @@ class MkDocsRenderer:
specified output directory.
Args:
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.
project (Project):
Project model containing modules to document.
out_dir (Path):
Directory where generated Markdown files will be written.
module_is_source (bool, optional):
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)
@@ -77,19 +84,23 @@ class MkDocsRenderer:
module_is_source: bool | None = None,
) -> None:
"""
Generate a ``README.md`` file from the root module docstring.
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 `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.
project (Project):
Project model containing documentation metadata.
docs_dir (Path):
Directory containing generated documentation sources.
module_is_source (bool, optional):
Whether the module is treated as the project source root.
"""
if not module_is_source:
@@ -136,10 +147,12 @@ class MkDocsRenderer:
Locate the root module corresponding to the project name.
Args:
project: Project model to inspect.
project (Project):
Project model to inspect.
Returns:
The root ``Module`` if found, otherwise ``None``.
Optional[Module]:
The root `Module` if found, otherwise `None`.
"""
for module in project.get_all_modules():
if module.path == project.name:
@@ -156,16 +169,22 @@ class MkDocsRenderer:
"""
Write documentation for a single module.
Package modules are rendered as ``index.md`` files inside their
Package modules are rendered as `index.md` files inside their
corresponding directories, while leaf modules are written as
standalone Markdown pages.
Args:
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.
module (Module):
Module to render.
packages (set[str]):
Set of module paths identified as packages.
out_dir (Path):
Base directory for generated documentation files.
module_is_source (bool, optional):
Whether the module acts as the documentation root directory.
"""
parts = module.path.split(".")
@@ -202,11 +221,15 @@ class MkDocsRenderer:
Generate Markdown content for a module documentation page.
Args:
title: Page title displayed in the documentation.
module_path: Dotted import path of the module.
title (str):
Page title displayed in the documentation.
module_path (str):
Dotted import path of the module.
Returns:
Markdown source containing a mkdocstrings directive.
str:
Markdown source containing a mkdocstrings directive.
"""
return (
f"# {title}\n\n"
@@ -219,11 +242,14 @@ class MkDocsRenderer:
out_dir: Path,
) -> None:
"""
Ensure that the root ``index.md`` page exists.
Ensure that the root `index.md` page exists.
Args:
project: Project model used for the page title.
out_dir: Documentation output directory.
project (Project):
Project model used for the page title.
out_dir (Path):
Documentation output directory.
"""
root_index = out_dir / "index.md"
@@ -246,10 +272,17 @@ class MkDocsRenderer:
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.
parts (list[str]):
Module path components.
out_dir (Path):
Documentation output directory.
link_target (str):
Link target used in the parent index.
title (str):
Display title for the link.
"""
if len(parts) == 1:
parent_index = out_dir / "index.md"