Vishesh 'ironeagle' Bangotra
b6e5114532
All checks were successful
continuous-integration/drone/tag Build is passing
92 lines
2.8 KiB
Python
92 lines
2.8 KiB
Python
"""
|
|
This module implements the MkDocsRenderer, which generates Markdown source files
|
|
compatible with the MkDocs 'material' theme and 'mkdocstrings' extension.
|
|
"""
|
|
|
|
from pathlib import Path
|
|
|
|
from docforge.model import Project
|
|
|
|
|
|
class MkDocsRenderer:
|
|
"""
|
|
Renderer that generates Markdown source files formatted for the MkDocs
|
|
'mkdocstrings' plugin.
|
|
"""
|
|
|
|
name = "mkdocs"
|
|
|
|
def generate_sources(self, project: Project, out_dir: Path) -> None:
|
|
"""
|
|
Produce a set of Markdown files in the output directory based on the
|
|
provided Project model.
|
|
|
|
Args:
|
|
project: The project model to render.
|
|
out_dir: Target directory for documentation files.
|
|
"""
|
|
modules = list(project.get_all_modules())
|
|
paths = {m.path for m in modules}
|
|
|
|
# Package detection (level-agnostic)
|
|
packages = {
|
|
p for p in paths
|
|
if any(other.startswith(p + ".") for other in paths)
|
|
}
|
|
|
|
for module in modules:
|
|
self._write_module(module, packages, out_dir)
|
|
|
|
# -------------------------
|
|
# Internal helpers
|
|
# -------------------------
|
|
def _write_module(self, module, packages: set[str], out_dir: Path) -> None:
|
|
"""
|
|
Write a single module's documentation file. Packages are written as
|
|
'index.md' inside their respective directories.
|
|
|
|
Args:
|
|
module: The module to write.
|
|
packages: A set of module paths that are identified as packages.
|
|
out_dir: The base output directory.
|
|
"""
|
|
parts = module.path.split(".")
|
|
|
|
if module.path in packages:
|
|
# package → index.md
|
|
dir_path = out_dir.joinpath(*parts)
|
|
dir_path.mkdir(parents=True, exist_ok=True)
|
|
|
|
md_path = dir_path / "index.md"
|
|
title = parts[-1].replace("_", " ").title()
|
|
else:
|
|
# leaf module → <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"
|
|
title = parts[-1].replace("_", " ").title()
|
|
|
|
content = self._render_markdown(title, module.path)
|
|
|
|
if md_path.exists() and md_path.read_text(encoding="utf-8") == content:
|
|
return
|
|
|
|
md_path.write_text(content, encoding="utf-8")
|
|
|
|
def _render_markdown(self, title: str, module_path: str) -> str:
|
|
"""
|
|
Generate the Markdown content for a module file.
|
|
|
|
Args:
|
|
title: The display title for the page.
|
|
module_path: The dotted path of the module to document.
|
|
|
|
Returns:
|
|
A string containing the Markdown source.
|
|
"""
|
|
return (
|
|
f"# {title}\n\n"
|
|
f"::: {module_path}\n"
|
|
)
|