updated doc strings
This commit is contained in:
@@ -1,13 +1,16 @@
|
||||
"""
|
||||
MkDocsRenderer
|
||||
MkDocs renderer implementation.
|
||||
|
||||
Generates Markdown source files compatible with MkDocs Material
|
||||
and mkdocstrings, ensuring:
|
||||
This module defines the ``MkDocsRenderer`` class, which generates Markdown
|
||||
documentation sources compatible with MkDocs Material and the mkdocstrings
|
||||
plugin.
|
||||
|
||||
- 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
|
||||
The renderer ensures a consistent documentation structure by:
|
||||
|
||||
- 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
|
||||
"""
|
||||
|
||||
from pathlib import Path
|
||||
@@ -16,8 +19,10 @@ from docforge.models import Project, Module
|
||||
|
||||
class MkDocsRenderer:
|
||||
"""
|
||||
Renderer that generates Markdown source files formatted for the MkDocs
|
||||
'mkdocstrings' plugin.
|
||||
Renderer that produces Markdown documentation for MkDocs.
|
||||
|
||||
Generated pages use mkdocstrings directives to reference Python modules,
|
||||
allowing MkDocs to render API documentation dynamically.
|
||||
"""
|
||||
|
||||
name = "mkdocs"
|
||||
@@ -25,6 +30,7 @@ class MkDocsRenderer:
|
||||
# -------------------------
|
||||
# Public API
|
||||
# -------------------------
|
||||
|
||||
def generate_sources(
|
||||
self,
|
||||
project: Project,
|
||||
@@ -32,18 +38,17 @@ class MkDocsRenderer:
|
||||
module_is_source: bool | None = None,
|
||||
) -> None:
|
||||
"""
|
||||
Produce a set of Markdown files in the output directory based on the
|
||||
provided Project models.
|
||||
Generate Markdown documentation files for a project.
|
||||
|
||||
This method renders a documentation structure from the provided
|
||||
project model and writes the resulting Markdown files to the
|
||||
specified output directory.
|
||||
|
||||
Args:
|
||||
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.
|
||||
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.
|
||||
"""
|
||||
out_dir.mkdir(parents=True, exist_ok=True)
|
||||
self._ensure_root_index(project, out_dir)
|
||||
@@ -51,7 +56,7 @@ class MkDocsRenderer:
|
||||
modules = list(project.get_all_modules())
|
||||
paths = {m.path for m in modules}
|
||||
|
||||
# Package detection (level-agnostic)
|
||||
# Detect packages (modules with children)
|
||||
packages = {
|
||||
p for p in paths
|
||||
if any(other.startswith(p + ".") for other in paths)
|
||||
@@ -72,22 +77,23 @@ class MkDocsRenderer:
|
||||
module_is_source: bool | None = None,
|
||||
) -> None:
|
||||
"""
|
||||
Generate README.md from the root package docstring.
|
||||
Generate a ``README.md`` file from the root module docstring.
|
||||
|
||||
Behavior:
|
||||
|
||||
- If module_is_source is True:
|
||||
README.md is generated at project root (docs_dir.parent)
|
||||
- If ``module_is_source`` is True, ``README.md`` is written to the
|
||||
project root directory.
|
||||
- If False, README generation is currently not implemented.
|
||||
|
||||
- If module_is_source is False:
|
||||
TODO: generate README.md inside respective module folders
|
||||
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.
|
||||
"""
|
||||
|
||||
# -------------------------
|
||||
# Only implement source-root mode
|
||||
# -------------------------
|
||||
if not module_is_source:
|
||||
# TODO: support per-module README generation
|
||||
# Future: support README generation per module
|
||||
return
|
||||
|
||||
readme_path = docs_dir.parent / "README.md"
|
||||
@@ -127,7 +133,13 @@ class MkDocsRenderer:
|
||||
|
||||
def _find_root_module(self, project: Project) -> Module | None:
|
||||
"""
|
||||
Find the root module matching the project name.
|
||||
Locate the root module corresponding to the project name.
|
||||
|
||||
Args:
|
||||
project: Project model to inspect.
|
||||
|
||||
Returns:
|
||||
The root ``Module`` if found, otherwise ``None``.
|
||||
"""
|
||||
for module in project.get_all_modules():
|
||||
if module.path == project.name:
|
||||
@@ -142,14 +154,18 @@ class MkDocsRenderer:
|
||||
module_is_source: bool | None = None,
|
||||
) -> None:
|
||||
"""
|
||||
Write a single module's documentation file. Packages are written as
|
||||
'index.md' inside their respective directories.
|
||||
Write documentation for a single module.
|
||||
|
||||
Package modules are rendered as ``index.md`` files inside their
|
||||
corresponding directories, while leaf modules are written as
|
||||
standalone Markdown pages.
|
||||
|
||||
Args:
|
||||
module: The module to write.
|
||||
packages: A set of module paths that are identified as packages.
|
||||
out_dir: The base output directory.
|
||||
module_is_source: Module is the source folder and to be treated as the root folder.
|
||||
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.
|
||||
"""
|
||||
|
||||
parts = module.path.split(".")
|
||||
@@ -160,15 +176,12 @@ class MkDocsRenderer:
|
||||
module_name, parts = parts[0], parts
|
||||
|
||||
if module.path in packages:
|
||||
# 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)
|
||||
|
||||
@@ -186,14 +199,14 @@ class MkDocsRenderer:
|
||||
|
||||
def _render_markdown(self, title: str, module_path: str) -> str:
|
||||
"""
|
||||
Generate the Markdown content for a module file.
|
||||
Generate Markdown content for a module documentation page.
|
||||
|
||||
Args:
|
||||
title: The display title for the page.
|
||||
module_path: The dotted path of the module to document.
|
||||
title: Page title displayed in the documentation.
|
||||
module_path: Dotted import path of the module.
|
||||
|
||||
Returns:
|
||||
A string containing the Markdown source.
|
||||
Markdown source containing a mkdocstrings directive.
|
||||
"""
|
||||
return (
|
||||
f"# {title}\n\n"
|
||||
@@ -205,6 +218,13 @@ class MkDocsRenderer:
|
||||
project: Project,
|
||||
out_dir: Path,
|
||||
) -> None:
|
||||
"""
|
||||
Ensure that the root ``index.md`` page exists.
|
||||
|
||||
Args:
|
||||
project: Project model used for the page title.
|
||||
out_dir: Documentation output directory.
|
||||
"""
|
||||
root_index = out_dir / "index.md"
|
||||
|
||||
if not root_index.exists():
|
||||
@@ -221,6 +241,16 @@ class MkDocsRenderer:
|
||||
link_target: str,
|
||||
title: str,
|
||||
) -> None:
|
||||
"""
|
||||
Ensure that parent package index files exist and contain links to
|
||||
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.
|
||||
"""
|
||||
if len(parts) == 1:
|
||||
parent_index = out_dir / "index.md"
|
||||
else:
|
||||
|
||||
Reference in New Issue
Block a user