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

Improve documentation look & feel via MkDocs Material template enhancements #5

Merged
aetos merged 5 commits from google-styled-doc into main 2026-03-07 10:50:19 +00:00
Conversation 0 Commits 5 Files Changed 51 +212 -41
9 changed files with 212 additions and 41 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Showing only changes of commit 219d6f9f87 - Show all commits

6
docforge/cli/mkdocs_utils.py
View File

@@ -32,6 +32,12 @@ def generate_sources(
module_is_source,
)
renderer.generate_readme(
project,
docs_dir,
module_is_source,
)
def generate_config(docs_dir: Path, nav_file: Path, template: Path | None, out: Path, site_name: str) -> None:
"""
Generate an mkdocs.yml configuration file.

88
docforge/renderers/mkdocs_renderer.py
View File

@@ -7,6 +7,7 @@ and mkdocstrings, ensuring:
- Root index.md always exists
- Parent package indexes are created automatically
- Child modules are linked in parent index files
- README.md can be generated from the root package docstring
"""
from pathlib import Path
@@ -35,9 +36,14 @@ class MkDocsRenderer:
provided Project models.
Args:
project: The project models to render.
out_dir: Target directory for documentation files.
module_is_source: Module is the source folder and to be treated as the root folder.
project:
The project model to render.
out_dir:
Target directory for generated Markdown.
module_is_source:
If True, treat the module as the root folder.
"""
out_dir.mkdir(parents=True, exist_ok=True)
self._ensure_root_index(project, out_dir)
@@ -59,9 +65,75 @@ class MkDocsRenderer:
module_is_source,
)
def generate_readme(
self,
project: Project,
docs_dir: Path,
module_is_source: bool | None = None,
) -> None:
"""
Generate README.md from the root package docstring.
Behavior:
- If module_is_source is True:
README.md is generated at project root (docs_dir.parent)
- If module_is_source is False:
TODO: generate README.md inside respective module folders
"""
# -------------------------
# Only implement source-root mode
# -------------------------
if not module_is_source:
# TODO: support per-module README generation
return
readme_path = docs_dir.parent / "README.md"
root_module = None
for module in project.get_all_modules():
if module.path == project.name:
root_module = module
break
if root_module is None:
return
doc = ""
if root_module.docstring:
doc = getattr(
root_module.docstring,
"value",
str(root_module.docstring),
)
content = (
f"# {project.name}\n\n"
f"{doc.strip()}\n"
)
if not readme_path.exists() or readme_path.read_text(encoding="utf-8") != content:
readme_path.write_text(
content,
encoding="utf-8",
)
# -------------------------
# Internal helpers
# -------------------------
def _find_root_module(self, project: Project) -> Module | None:
"""
Find the root module matching the project name.
"""
for module in project.get_all_modules():
if module.path == project.name:
return module
return None
def _write_module(
self,
module: Module,
@@ -79,6 +151,7 @@ class MkDocsRenderer:
out_dir: The base output directory.
module_is_source: Module is the source folder and to be treated as the root folder.
"""
parts = module.path.split(".")
if module_is_source:
@@ -90,12 +163,15 @@ class MkDocsRenderer:
# Package → directory/index.md
dir_path = out_dir.joinpath(*parts)
dir_path.mkdir(parents=True, exist_ok=True)
md_path = dir_path / "index.md"
link_target = f"{parts[-1]}/" if parts else None
else:
# Leaf module → parent_dir/<name>.md
dir_path = out_dir.joinpath(*parts[:-1])
dir_path.mkdir(parents=True, exist_ok=True)
md_path = dir_path / f"{parts[-1]}.md"
link_target = f"{parts[-1]}.md" if parts else None
@@ -127,7 +203,7 @@ class MkDocsRenderer:
def _ensure_root_index(
self,
project: Project,
out_dir: Path
out_dir: Path,
) -> None:
root_index = out_dir / "index.md"
@@ -147,14 +223,11 @@ class MkDocsRenderer:
) -> None:
if len(parts) == 1:
parent_index = out_dir / "index.md"
link = f"- [{title}]({link_target})\n"
else:
parent_dir = out_dir.joinpath(*parts[:-1])
parent_dir.mkdir(parents=True, exist_ok=True)
parent_index = parent_dir / "index.md"
link = f"- [{title}]({link_target})\n"
if not parent_index.exists():
parent_title = parts[-2].replace("_", " ").title()
parent_index.write_text(
@@ -164,5 +237,6 @@ class MkDocsRenderer:
content = parent_index.read_text(encoding="utf-8")
link = f"- [{title}]({link_target})\n"
if link not in content:
parent_index.write_text(content + link, encoding="utf-8")

7
docforge/renderers/mkdocs_renderer.pyi
View File

@@ -12,6 +12,13 @@ class MkDocsRenderer:
module_is_source: bool | None = None,
) -> None: ...
def generate_readme(
self,
project: Project,
docs_dir: Path,
module_is_source: bool | None = None,
) -> None:
def _write_module(
self,
module: Module,

9
mcp_docs/modules/docforge.cli.commands.json
View File

@@ -139,7 +139,14 @@
"kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.MkDocsRenderer.generate_sources",
"signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources')>",
"docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project: The project models to render.\n out_dir: Target directory for documentation files.\n module_is_source: Module is the source folder and to be treated as the root folder."
"docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project:\n The project model to render.\n\n out_dir:\n Target directory for generated Markdown.\n\n module_is_source:\n If True, treat the module as the root folder."
},
"generate_readme": {
"name": "generate_readme",
"kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.MkDocsRenderer.generate_readme",
"signature": "<bound method Alias.signature of Alias('generate_readme', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_readme')>",
"docstring": "Generate README.md from the root package docstring.\n\nBehavior:\n\n- If module_is_source is True:\n README.md is generated at project root (docs_dir.parent)\n\n- If module_is_source is False:\n TODO: generate README.md inside respective module folders"
}
}
},

26
mcp_docs/modules/docforge.cli.json
View File

@@ -169,7 +169,14 @@
"kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.MkDocsRenderer.generate_sources",
"signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources')>",
"docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project: The project models to render.\n out_dir: Target directory for documentation files.\n module_is_source: Module is the source folder and to be treated as the root folder."
"docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project:\n The project model to render.\n\n out_dir:\n Target directory for generated Markdown.\n\n module_is_source:\n If True, treat the module as the root folder."
},
"generate_readme": {
"name": "generate_readme",
"kind": "function",
"path": "docforge.cli.commands.mkdocs_utils.MkDocsRenderer.generate_readme",
"signature": "<bound method Alias.signature of Alias('generate_readme', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_readme')>",
"docstring": "Generate README.md from the root package docstring.\n\nBehavior:\n\n- If module_is_source is True:\n README.md is generated at project root (docs_dir.parent)\n\n- If module_is_source is False:\n TODO: generate README.md inside respective module folders"
}
}
},
@@ -601,7 +608,14 @@
"kind": "function",
"path": "docforge.cli.mkdocs_utils.MkDocsRenderer.generate_sources",
"signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources')>",
"docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project: The project models to render.\n out_dir: Target directory for documentation files.\n module_is_source: Module is the source folder and to be treated as the root folder."
"docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project:\n The project model to render.\n\n out_dir:\n Target directory for generated Markdown.\n\n module_is_source:\n If True, treat the module as the root folder."
},
"generate_readme": {
"name": "generate_readme",
"kind": "function",
"path": "docforge.cli.mkdocs_utils.MkDocsRenderer.generate_readme",
"signature": "<bound method Alias.signature of Alias('generate_readme', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_readme')>",
"docstring": "Generate README.md from the root package docstring.\n\nBehavior:\n\n- If module_is_source is True:\n README.md is generated at project root (docs_dir.parent)\n\n- If module_is_source is False:\n TODO: generate README.md inside respective module folders"
}
}
},
@@ -639,28 +653,28 @@
"name": "generate_sources",
"kind": "function",
"path": "docforge.cli.mkdocs_utils.generate_sources",
"signature": "<bound method Function.signature of Function('generate_sources', 9, 33)>",
"signature": "<bound method Function.signature of Function('generate_sources', 9, 39)>",
"docstring": "Generate Markdown source files for the specified module.\n\nArgs:\n module: The dotted path of the primary module to document.\n project_name: Optional override for the project name.\n docs_dir: Directory where the generated Markdown files will be written.\n module_is_source: Module is the source folder and to be treated as the root folder."
},
"generate_config": {
"name": "generate_config",
"kind": "function",
"path": "docforge.cli.mkdocs_utils.generate_config",
"signature": "<bound method Function.signature of Function('generate_config', 35, 69)>",
"signature": "<bound method Function.signature of Function('generate_config', 41, 75)>",
"docstring": "Generate an mkdocs.yml configuration file.\n\nArgs:\n docs_dir: Path to the directory containing documentation Markdown files.\n nav_file: Path to the docforge.nav.yml specification.\n template: Optional path to an mkdocs.yml template (overrides built-in).\n out: Path where the final mkdocs.yml will be written.\n site_name: The display name for the documentation site."
},
"build": {
"name": "build",
"kind": "function",
"path": "docforge.cli.mkdocs_utils.build",
"signature": "<bound method Function.signature of Function('build', 71, 84)>",
"signature": "<bound method Function.signature of Function('build', 77, 90)>",
"docstring": "Build the documentation site using MkDocs.\n\nArgs:\n mkdocs_yml: Path to the mkdocs.yml configuration file."
},
"serve": {
"name": "serve",
"kind": "function",
"path": "docforge.cli.mkdocs_utils.serve",
"signature": "<bound method Function.signature of Function('serve', 86, 97)>",
"signature": "<bound method Function.signature of Function('serve', 92, 103)>",
"docstring": "Serve the documentation site with live-reload using MkDocs.\n\nArgs:\n mkdocs_yml: Path to the mkdocs.yml configuration file."
}
}

17
mcp_docs/modules/docforge.cli.mkdocs_utils.json
View File

@@ -81,7 +81,14 @@
"kind": "function",
"path": "docforge.cli.mkdocs_utils.MkDocsRenderer.generate_sources",
"signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources')>",
"docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project: The project models to render.\n out_dir: Target directory for documentation files.\n module_is_source: Module is the source folder and to be treated as the root folder."
"docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project:\n The project model to render.\n\n out_dir:\n Target directory for generated Markdown.\n\n module_is_source:\n If True, treat the module as the root folder."
},
"generate_readme": {
"name": "generate_readme",
"kind": "function",
"path": "docforge.cli.mkdocs_utils.MkDocsRenderer.generate_readme",
"signature": "<bound method Alias.signature of Alias('generate_readme', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_readme')>",
"docstring": "Generate README.md from the root package docstring.\n\nBehavior:\n\n- If module_is_source is True:\n README.md is generated at project root (docs_dir.parent)\n\n- If module_is_source is False:\n TODO: generate README.md inside respective module folders"
}
}
},
@@ -119,28 +126,28 @@
"name": "generate_sources",
"kind": "function",
"path": "docforge.cli.mkdocs_utils.generate_sources",
"signature": "<bound method Function.signature of Function('generate_sources', 9, 33)>",
"signature": "<bound method Function.signature of Function('generate_sources', 9, 39)>",
"docstring": "Generate Markdown source files for the specified module.\n\nArgs:\n module: The dotted path of the primary module to document.\n project_name: Optional override for the project name.\n docs_dir: Directory where the generated Markdown files will be written.\n module_is_source: Module is the source folder and to be treated as the root folder."
},
"generate_config": {
"name": "generate_config",
"kind": "function",
"path": "docforge.cli.mkdocs_utils.generate_config",
"signature": "<bound method Function.signature of Function('generate_config', 35, 69)>",
"signature": "<bound method Function.signature of Function('generate_config', 41, 75)>",
"docstring": "Generate an mkdocs.yml configuration file.\n\nArgs:\n docs_dir: Path to the directory containing documentation Markdown files.\n nav_file: Path to the docforge.nav.yml specification.\n template: Optional path to an mkdocs.yml template (overrides built-in).\n out: Path where the final mkdocs.yml will be written.\n site_name: The display name for the documentation site."
},
"build": {
"name": "build",
"kind": "function",
"path": "docforge.cli.mkdocs_utils.build",
"signature": "<bound method Function.signature of Function('build', 71, 84)>",
"signature": "<bound method Function.signature of Function('build', 77, 90)>",
"docstring": "Build the documentation site using MkDocs.\n\nArgs:\n mkdocs_yml: Path to the mkdocs.yml configuration file."
},
"serve": {
"name": "serve",
"kind": "function",
"path": "docforge.cli.mkdocs_utils.serve",
"signature": "<bound method Function.signature of Function('serve', 86, 97)>",
"signature": "<bound method Function.signature of Function('serve', 92, 103)>",
"docstring": "Serve the documentation site with live-reload using MkDocs.\n\nArgs:\n mkdocs_yml: Path to the mkdocs.yml configuration file."
}
}

61
mcp_docs/modules/docforge.json
View File

File diff suppressed because one or more lines are too long

24
mcp_docs/modules/docforge.renderers.json
View File

@@ -23,7 +23,14 @@
"kind": "function",
"path": "docforge.renderers.MkDocsRenderer.generate_sources",
"signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources')>",
"docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project: The project models to render.\n out_dir: Target directory for documentation files.\n module_is_source: Module is the source folder and to be treated as the root folder."
"docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project:\n The project model to render.\n\n out_dir:\n Target directory for generated Markdown.\n\n module_is_source:\n If True, treat the module as the root folder."
},
"generate_readme": {
"name": "generate_readme",
"kind": "function",
"path": "docforge.renderers.MkDocsRenderer.generate_readme",
"signature": "<bound method Alias.signature of Alias('generate_readme', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_readme')>",
"docstring": "Generate README.md from the root package docstring.\n\nBehavior:\n\n- If module_is_source is True:\n README.md is generated at project root (docs_dir.parent)\n\n- If module_is_source is False:\n TODO: generate README.md inside respective module folders"
}
}
},
@@ -409,7 +416,7 @@
"kind": "module",
"path": "docforge.renderers.mkdocs_renderer",
"signature": null,
"docstring": "MkDocsRenderer\n\nGenerates Markdown source files compatible with MkDocs Material\nand mkdocstrings, ensuring:\n\n- Root index.md always exists\n- Parent package indexes are created automatically\n- Child modules are linked in parent index files",
"docstring": "MkDocsRenderer\n\nGenerates Markdown source files compatible with MkDocs Material\nand mkdocstrings, ensuring:\n\n- Root index.md always exists\n- Parent package indexes are created automatically\n- Child modules are linked in parent index files\n- README.md can be generated from the root package docstring",
"members": {
"Path": {
"name": "Path",
@@ -524,7 +531,7 @@
"name": "MkDocsRenderer",
"kind": "class",
"path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer",
"signature": "<bound method Class.signature of Class('MkDocsRenderer', 16, 168)>",
"signature": "<bound method Class.signature of Class('MkDocsRenderer', 17, 242)>",
"docstring": "Renderer that generates Markdown source files formatted for the MkDocs\n'mkdocstrings' plugin.",
"members": {
"name": {
@@ -538,8 +545,15 @@
"name": "generate_sources",
"kind": "function",
"path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources",
"signature": "<bound method Function.signature of Function('generate_sources', 27, 60)>",
"docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project: The project models to render.\n out_dir: Target directory for documentation files.\n module_is_source: Module is the source folder and to be treated as the root folder."
"signature": "<bound method Function.signature of Function('generate_sources', 28, 66)>",
"docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project:\n The project model to render.\n\n out_dir:\n Target directory for generated Markdown.\n\n module_is_source:\n If True, treat the module as the root folder."
},
"generate_readme": {
"name": "generate_readme",
"kind": "function",
"path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_readme",
"signature": "<bound method Function.signature of Function('generate_readme', 68, 122)>",
"docstring": "Generate README.md from the root package docstring.\n\nBehavior:\n\n- If module_is_source is True:\n README.md is generated at project root (docs_dir.parent)\n\n- If module_is_source is False:\n TODO: generate README.md inside respective module folders"
}
}
}

15
mcp_docs/modules/docforge.renderers.mkdocs_renderer.json
View File

@@ -2,7 +2,7 @@
"module": "docforge.renderers.mkdocs_renderer",
"content": {
"path": "docforge.renderers.mkdocs_renderer",
"docstring": "MkDocsRenderer\n\nGenerates Markdown source files compatible with MkDocs Material\nand mkdocstrings, ensuring:\n\n- Root index.md always exists\n- Parent package indexes are created automatically\n- Child modules are linked in parent index files",
"docstring": "MkDocsRenderer\n\nGenerates Markdown source files compatible with MkDocs Material\nand mkdocstrings, ensuring:\n\n- Root index.md always exists\n- Parent package indexes are created automatically\n- Child modules are linked in parent index files\n- README.md can be generated from the root package docstring",
"objects": {
"Path": {
"name": "Path",
@@ -117,7 +117,7 @@
"name": "MkDocsRenderer",
"kind": "class",
"path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer",
"signature": "<bound method Class.signature of Class('MkDocsRenderer', 16, 168)>",
"signature": "<bound method Class.signature of Class('MkDocsRenderer', 17, 242)>",
"docstring": "Renderer that generates Markdown source files formatted for the MkDocs\n'mkdocstrings' plugin.",
"members": {
"name": {
@@ -131,8 +131,15 @@
"name": "generate_sources",
"kind": "function",
"path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources",
"signature": "<bound method Function.signature of Function('generate_sources', 27, 60)>",
"docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project: The project models to render.\n out_dir: Target directory for documentation files.\n module_is_source: Module is the source folder and to be treated as the root folder."
"signature": "<bound method Function.signature of Function('generate_sources', 28, 66)>",
"docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project:\n The project model to render.\n\n out_dir:\n Target directory for generated Markdown.\n\n module_is_source:\n If True, treat the module as the root folder."
},
"generate_readme": {
"name": "generate_readme",
"kind": "function",
"path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_readme",
"signature": "<bound method Function.signature of Function('generate_readme', 68, 122)>",
"docstring": "Generate README.md from the root package docstring.\n\nBehavior:\n\n- If module_is_source is True:\n README.md is generated at project root (docs_dir.parent)\n\n- If module_is_source is False:\n TODO: generate README.md inside respective module folders"
}
}
}