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

standardize packaging, tooling, docs, CI, and licensing

Browse Source
This commit is contained in:
Vishesh 'ironeagle' Bangotra
2026-09-10 18:49:04 +05:30
parent 8253c25928
commit 0129268cd3
61 changed files with 429 additions and 273 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docforge/renderers/__init__.pyi
View File

@@ -1,5 +1,5 @@
from .mkdocs_renderer import MkDocsRenderer
from .mcp_renderer import MCPRenderer
from .mkdocs_renderer import MkDocsRenderer
__all__ = [
"MkDocsRenderer",

2
docforge/renderers/base.pyi
View File

@@ -3,7 +3,6 @@ from typing import Protocol
from docforge.models import Project
class RendererConfig:
"""Renderer configuration container."""
@@ -12,7 +11,6 @@ class RendererConfig:
def __init__(self, out_dir: Path, project: Project) -> None: ...
class DocRenderer(Protocol):
"""Renderer interface."""

28
docforge/renderers/mcp_renderer.py
View File

@@ -9,9 +9,8 @@ resources compatible with the Model Context Protocol (MCP).
import json
from pathlib import Path
from typing import Dict, List
from docforge.models import Project, Module, DocObject
from docforge.models import DocObject, Module, Project
class MCPRenderer:
@@ -42,15 +41,17 @@ class MCPRenderer:
modules_dir = out_dir / "modules"
modules_dir.mkdir(parents=True, exist_ok=True)
nav: List[Dict[str, str]] = []
nav: list[dict[str, str]] = []
for module in project.get_all_modules():
self._write_module(module, modules_dir)
nav.append({
"module": module.path,
"resource": f"doc://modules/{module.path}",
})
nav.append(
{
"module": module.path,
"resource": f"doc://modules/{module.path}",
}
)
# Write nav.json
(out_dir / "nav.json").write_text(
@@ -91,7 +92,7 @@ class MCPRenderer:
out.parent.mkdir(parents=True, exist_ok=True)
out.write_text(self._json(payload), encoding="utf-8")
def _render_module(self, module: Module) -> Dict:
def _render_module(self, module: Module) -> dict:
"""
Convert a Module model into MCP-compatible structured data.
@@ -103,7 +104,7 @@ class MCPRenderer:
Dict:
Dictionary representing the module and its documented objects.
"""
data: Dict = {
data: dict = {
"path": module.path,
"docstring": module.docstring,
"objects": {},
@@ -114,7 +115,7 @@ class MCPRenderer:
return data
def _render_object(self, obj: DocObject) -> Dict:
def _render_object(self, obj: DocObject) -> dict:
"""
Recursively convert a DocObject into structured MCP data.
@@ -126,7 +127,7 @@ class MCPRenderer:
Dict:
Dictionary describing the object and any nested members.
"""
data: Dict = {
data: dict = {
"name": obj.name,
"kind": obj.kind,
"path": obj.path,
@@ -137,14 +138,13 @@ class MCPRenderer:
members = list(obj.get_all_members())
if members:
data["members"] = {
member.name: self._render_object(member)
for member in members
member.name: self._render_object(member) for member in members
}
return data
@staticmethod
def _json(data: Dict) -> str:
def _json(data: dict) -> str:
"""
Serialize data to formatted JSON.

11
docforge/renderers/mcp_renderer.pyi
View File

@@ -1,8 +1,7 @@
from pathlib import Path
from typing import Dict, List
from docforge.models import Project, Module, DocObject
from typing import Any
from docforge.models import DocObject, Module, Project
class MCPRenderer:
"""Renderer that emits MCP-native JSON resources from docforge models."""
@@ -15,12 +14,12 @@ class MCPRenderer:
def _write_module(self, module: Module, modules_dir: Path) -> None:
"""Serialize a module into an MCP JSON resource."""
def _render_module(self, module: Module) -> Dict:
def _render_module(self, module: Module) -> dict[str, Any]:
"""Render a Module into MCP-friendly structured data."""
def _render_object(self, obj: DocObject) -> Dict:
def _render_object(self, obj: DocObject) -> dict[str, Any]:
"""Recursively render a DocObject into structured MCP data."""
@staticmethod
def _json(data: Dict) -> str:
def _json(data: dict[str, Any]) -> str:
"""Serialize structured data to formatted JSON."""

24
docforge/renderers/mkdocs_renderer.py
View File

@@ -16,7 +16,8 @@ The renderer ensures a consistent documentation structure by:
"""
from pathlib import Path
from docforge.models import Project, Module
from docforge.models import Module, Project
class MkDocsRenderer:
@@ -65,8 +66,7 @@ class MkDocsRenderer:
# Detect packages (modules with children)
packages = {
p for p in paths
if any(other.startswith(p + ".") for other in paths)
p for p in paths if any(other.startswith(p + ".") for other in paths)
}
for module in modules:
@@ -127,12 +127,12 @@ class MkDocsRenderer:
str(root_module.docstring),
)
content = (
f"# {project.name}\n\n"
f"{doc.strip()}\n"
)
content = f"# {project.name}\n\n" f"{doc.strip()}\n"
if not readme_path.exists() or readme_path.read_text(encoding="utf-8") != content:
if (
not readme_path.exists()
or readme_path.read_text(encoding="utf-8") != content
):
readme_path.write_text(
content,
encoding="utf-8",
@@ -231,10 +231,7 @@ class MkDocsRenderer:
str:
Markdown source containing a mkdocstrings directive.
"""
return (
f"# {title}\n\n"
f"::: {module_path}\n"
)
return f"# {title}\n\n" f"::: {module_path}\n"
def _ensure_root_index(
self,
@@ -255,8 +252,7 @@ class MkDocsRenderer:
if not root_index.exists():
root_index.write_text(
f"# {project.name}\n\n"
"## Modules\n\n",
f"# {project.name}\n\n" "## Modules\n\n",
encoding="utf-8",
)

15
docforge/renderers/mkdocs_renderer.pyi
View File

@@ -1,6 +1,6 @@
from pathlib import Path
from docforge.models import Project, Module
from docforge.models import Module, Project
class MkDocsRenderer:
name: str
@@ -11,14 +11,12 @@ class MkDocsRenderer:
out_dir: Path,
module_is_source: bool | None = None,
) -> None: ...
def generate_readme(
self,
project: Project,
docs_dir: Path,
module_is_source: bool | None = None,
) -> None:
) -> None: ...
def _write_module(
self,
module: Module,
@@ -26,9 +24,8 @@ class MkDocsRenderer:
out_dir: Path,
module_is_source: bool | None = None,
) -> None: ...
def _render_markdown(self, title: str, module_path: str) -> str: ...
def _ensure_root_index(self, project, out_dir) -> None: ...
def _ensure_parent_index(self, parts, out_dir, link_target, title) -> None: ...
def _ensure_root_index(self, project: Project, out_dir: Path) -> None: ...
def _ensure_parent_index(
self, parts: list[str], out_dir: Path, link_target: str, title: str
) -> None: ...