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

chore(release): 0.0.7

Browse Source 
Squash-merge lib-standardisation: adopt repo standards across packaging,
tooling, docs, and CI.

- standardize pyproject.toml (canonical packaging, lint config, extras, GSDFC pydoclint)
- add py.typed marker, modernize type hints and Google-style docstrings
- nest generated docs under docs/lib and docs/mcp; add hand-written wiki
- adopt standard Type A PyPI CI pipeline (tag==version guard + quality gate)
- promote generated CHANGELOG.md; bump version to 0.0.7
This commit is contained in:
Vishesh 'ironeagle' Bangotra
2026-10-17 02:16:44 +05:30
parent 8253c25928
commit 06ffd2febd
149 changed files with 7132 additions and 4594 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."""

34
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"docs://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.
@@ -100,10 +101,10 @@ class MCPRenderer:
Module instance to convert.
Returns:
Dict:
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.
@@ -123,10 +124,10 @@ class MCPRenderer:
Documentation object to convert.
Returns:
Dict:
dict:
Dictionary describing the object and any nested members.
"""
data: Dict = {
data: dict = {
"name": obj.name,
"kind": obj.kind,
"path": obj.path,
@@ -137,19 +138,18 @@ 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.
Args:
data (Dict):
data (dict):
Dictionary to serialize.
Returns:

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."""

49
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:
@@ -53,7 +54,7 @@ class MkDocsRenderer:
out_dir (Path):
Directory where generated Markdown files will be written.
module_is_source (bool, optional):
module_is_source (bool | None):
If True, treat the specified module as the documentation root
rather than nesting it inside a folder.
"""
@@ -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:
@@ -82,15 +82,15 @@ class MkDocsRenderer:
project: Project,
docs_dir: Path,
module_is_source: bool | None = None,
readme_dir: Path | 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.
Notes:
- 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):
@@ -99,15 +99,20 @@ class MkDocsRenderer:
docs_dir (Path):
Directory containing generated documentation sources.
module_is_source (bool, optional):
module_is_source (bool | None):
Whether the module is treated as the project source root.
readme_dir (Path | None):
Directory where the generated README.md should be written.
Defaults to the parent of `docs_dir`.
"""
if not module_is_source:
# Future: support README generation per module
return
readme_path = docs_dir.parent / "README.md"
readme_root = readme_dir if readme_dir is not None else docs_dir.parent
readme_path = readme_root / "README.md"
root_module = None
for module in project.get_all_modules():
@@ -127,12 +132,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",
@@ -151,7 +156,7 @@ class MkDocsRenderer:
Project model to inspect.
Returns:
Optional[Module]:
Module | None:
The root `Module` if found, otherwise `None`.
"""
for module in project.get_all_modules():
@@ -183,7 +188,7 @@ class MkDocsRenderer:
out_dir (Path):
Base directory for generated documentation files.
module_is_source (bool, optional):
module_is_source (bool | None):
Whether the module acts as the documentation root directory.
"""
@@ -231,10 +236,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 +257,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: ...