Vishesh 'ironeagle' Bangotra
582b6809a0
- fix GSDFC spec contradictions in __init__ docstring (parenthesized types, fenced-block rule) and sync generated README - rewrite docstrings across loaders, models, nav, servers, renderers, cli; sync .pyi stubs - add pydoclint (google style) gate to dev extras and pyproject config - fix mcp nav resources doc:// -> docs:// - refresh docs/lib and docs/mcp, drop stale docforge/ duplicate group - update wiki pages and add GSDFC + MCP guides under 05_development
358 lines
10 KiB
Python
358 lines
10 KiB
Python
"""
|
|
# Summary
|
|
|
|
Utilities for working with MkDocs in the doc-forge CLI.
|
|
|
|
---
|
|
|
|
Notes:
|
|
- A single generated `mkdocs.yml` serves lib, api, and wiki content with
|
|
merged navigation. Wiki navigation, when enabled, precedes every other
|
|
group and its `index.md` becomes the site `Home`.
|
|
|
|
---
|
|
"""
|
|
|
|
import os
|
|
from collections.abc import Iterable
|
|
from importlib import resources
|
|
from pathlib import Path
|
|
|
|
import click
|
|
import yaml
|
|
|
|
from docforge.loaders import GriffeLoader, discover_module_paths
|
|
from docforge.nav import (
|
|
MkDocsNavEmitter,
|
|
build_wiki_nav,
|
|
load_nav_spec,
|
|
resolve_nav,
|
|
)
|
|
from docforge.renderers import MkDocsRenderer
|
|
|
|
|
|
def generate_sources(
|
|
module: str,
|
|
docs_dir: Path,
|
|
project_name: str | None = None,
|
|
module_is_source: bool | None = None,
|
|
readme_dir: Path | None = None,
|
|
) -> None:
|
|
"""
|
|
Generate MkDocs Markdown sources for a Python module.
|
|
|
|
This function introspects the specified module, builds the internal
|
|
documentation model, and renders Markdown documentation files for
|
|
use with MkDocs.
|
|
|
|
Args:
|
|
module (str):
|
|
Python module import path used as the entry point for
|
|
documentation generation.
|
|
|
|
docs_dir (Path):
|
|
Directory where the generated Markdown files will be written.
|
|
|
|
project_name (str | None):
|
|
Optional override for the project name used in documentation metadata.
|
|
|
|
module_is_source (bool | None):
|
|
If True, treat the specified module directory as the project root
|
|
rather than a nested module.
|
|
|
|
readme_dir (Path | None):
|
|
Directory where the generated README.md should be written. If not
|
|
provided, defaults to the parent of ``docs_dir``.
|
|
"""
|
|
loader = GriffeLoader()
|
|
discovered_paths = discover_module_paths(module)
|
|
project = loader.load_project(discovered_paths, project_name)
|
|
|
|
renderer = MkDocsRenderer()
|
|
renderer.generate_sources(
|
|
project,
|
|
docs_dir,
|
|
module_is_source,
|
|
)
|
|
|
|
renderer.generate_readme(
|
|
project,
|
|
docs_dir,
|
|
module_is_source,
|
|
readme_dir,
|
|
)
|
|
|
|
|
|
def generate_config(
|
|
docs_dir: Path,
|
|
nav_file: Path,
|
|
template: Path | None,
|
|
out: Path,
|
|
site_name: str,
|
|
modes: Iterable[str] | None = None,
|
|
site_description: str | None = None,
|
|
site_author: str | None = None,
|
|
wiki_dir: Path | None = None,
|
|
) -> None:
|
|
"""
|
|
Generate an `mkdocs.yml` configuration file.
|
|
|
|
The configuration is created by combining a template configuration
|
|
with a navigation structure derived from the docforge navigation
|
|
specification (and, when a wiki directory is provided, from the wiki
|
|
file structure).
|
|
|
|
The ``docs_dir`` is always written relative to the MkDocs root and is
|
|
expected to be the shared documentation parent (for example ``docs``),
|
|
with generated sources nested under ``lib/`` or ``api/`` subdirectories
|
|
and hand-written wiki content under a ``wiki/`` subdirectory.
|
|
|
|
Args:
|
|
docs_dir (Path):
|
|
Shared documentation root used as the MkDocs ``docs_dir``.
|
|
|
|
nav_file (Path):
|
|
Path to the `docforge.nav.yml` navigation specification.
|
|
|
|
template (Path | None):
|
|
Optional path to a fully custom MkDocs configuration template.
|
|
If not provided, built-in templates are merged; the provided
|
|
template replaces the built-in templates entirely.
|
|
|
|
out (Path):
|
|
Destination path where the generated `mkdocs.yml` file will be written.
|
|
|
|
site_name (str):
|
|
Display name for the generated documentation site.
|
|
|
|
modes (Iterable[str] | None):
|
|
Documentation modes to enable. Each mode contributes its own
|
|
built-in template fragment (for example ``lib``, ``api``, or
|
|
``wiki``), merged on top of the shared ``mkdocs.common.yml``
|
|
template.
|
|
|
|
site_description (str | None):
|
|
Optional site description written into the configuration.
|
|
|
|
site_author (str | None):
|
|
Optional site author written into the configuration.
|
|
|
|
wiki_dir (Path | None):
|
|
Optional path to a hand-written wiki directory (for example
|
|
``docs/wiki``). When provided, the site navigation is derived
|
|
from the wiki file structure and placed before the navigation
|
|
groups defined in ``nav_file``.
|
|
|
|
Raises:
|
|
click.FileError:
|
|
If the navigation specification, template, or wiki directory
|
|
cannot be found.
|
|
"""
|
|
if not nav_file.exists() and wiki_dir is None:
|
|
raise click.FileError(str(nav_file), hint="Nav spec not found")
|
|
|
|
nav_block: list[dict] = []
|
|
if nav_file.exists():
|
|
spec = load_nav_spec(nav_file)
|
|
resolved = resolve_nav(spec, docs_dir)
|
|
nav_block = MkDocsNavEmitter().emit(resolved)
|
|
else:
|
|
spec = None
|
|
|
|
if wiki_dir is not None:
|
|
if not wiki_dir.exists():
|
|
raise click.FileError(str(wiki_dir), hint="Wiki dir not found")
|
|
wiki_nav = build_wiki_nav(wiki_dir)
|
|
if wiki_nav:
|
|
nav_block = wiki_nav + [entry for entry in nav_block if "Home" not in entry]
|
|
|
|
data = _load_template(template, modes)
|
|
|
|
data["site_name"] = site_name
|
|
if site_description:
|
|
data["site_description"] = site_description
|
|
if site_author:
|
|
data["site_author"] = site_author
|
|
data["docs_dir"] = Path(os.path.relpath(docs_dir, out.parent)).as_posix()
|
|
data["nav"] = nav_block
|
|
|
|
if spec is not None and spec.icon:
|
|
theme = data.setdefault("theme", {})
|
|
if not isinstance(theme, dict):
|
|
theme = {}
|
|
theme["icon"] = spec.icon
|
|
data["theme"] = theme
|
|
|
|
out.write_text(yaml.safe_dump(data, sort_keys=False), encoding="utf-8")
|
|
|
|
|
|
def _load_template(
|
|
template: Path | None,
|
|
modes: Iterable[str] | None,
|
|
) -> dict:
|
|
"""
|
|
Load the MkDocs configuration template.
|
|
|
|
When a custom template path is provided, it is used as-is. Otherwise the
|
|
shared ``mkdocs.common.yml`` template is deep-merged with the fragments
|
|
contributed by each enabled mode (``lib``, ``api``, or ``wiki``).
|
|
|
|
Args:
|
|
template (Path | None):
|
|
Optional fully custom template that replaces the built-ins.
|
|
|
|
modes (Iterable[str] | None):
|
|
Documentation modes whose template fragments should be merged.
|
|
|
|
Returns:
|
|
dict:
|
|
Merged MkDocs configuration mapping.
|
|
|
|
Raises:
|
|
click.FileError:
|
|
If a referenced template file cannot be found.
|
|
"""
|
|
if template is not None:
|
|
if not template.exists():
|
|
raise click.FileError(str(template), hint="Template not found")
|
|
return yaml.safe_load(template.read_text(encoding="utf-8"))
|
|
|
|
data: dict = {}
|
|
active_modes = list(modes) if modes else ["lib"]
|
|
parts = ["common", *active_modes]
|
|
|
|
seen: set[str] = set()
|
|
for part_name in parts:
|
|
if part_name in seen:
|
|
continue
|
|
seen.add(part_name)
|
|
|
|
text = (
|
|
resources.files("docforge.templates")
|
|
.joinpath(f"mkdocs.{part_name}.yml")
|
|
.read_text(encoding="utf-8")
|
|
)
|
|
part: dict = yaml.safe_load(text)
|
|
data = _deep_merge(data, part)
|
|
|
|
return data
|
|
|
|
|
|
def _item_name(item: object) -> str:
|
|
"""
|
|
Return the identifying name of a list entry.
|
|
|
|
String entries identify as themselves; mapping entries identify by their
|
|
first key. This is used to deduplicate plugin and extension lists.
|
|
|
|
Args:
|
|
item (object):
|
|
List entry, either a string or a single-key mapping.
|
|
|
|
Returns:
|
|
str:
|
|
The identifying name of the entry.
|
|
"""
|
|
if isinstance(item, dict):
|
|
return next(iter(item.keys()), "")
|
|
return str(item)
|
|
|
|
|
|
def _merge_list(base: list, added: list) -> list:
|
|
"""
|
|
Merge two lists, preserving order and dropping duplicates by name.
|
|
|
|
Args:
|
|
base (list):
|
|
Existing list entries.
|
|
added (list):
|
|
Entries to append when not already present.
|
|
|
|
Returns:
|
|
list:
|
|
Merged list with duplicates removed.
|
|
"""
|
|
result = list(base)
|
|
names = {_item_name(item) for item in result}
|
|
for item in added:
|
|
name = _item_name(item)
|
|
if name not in names:
|
|
result.append(item)
|
|
names.add(name)
|
|
return result
|
|
|
|
|
|
def _deep_merge(base: dict, part: dict) -> dict:
|
|
"""
|
|
Deep merge a template fragment into a base configuration.
|
|
|
|
Mappings are merged recursively, while lists are combined by
|
|
deduplicating entries by their identifying name. Non-container values in
|
|
the fragment override the base.
|
|
|
|
Args:
|
|
base (dict):
|
|
Configuration being built up.
|
|
part (dict):
|
|
Template fragment to merge into the base.
|
|
|
|
Returns:
|
|
dict:
|
|
The merged configuration.
|
|
"""
|
|
for key, value in part.items():
|
|
if isinstance(value, dict) and isinstance(base.get(key), dict):
|
|
base[key] = _deep_merge(base[key], value)
|
|
elif isinstance(value, list) and isinstance(base.get(key), list):
|
|
base[key] = _merge_list(base[key], value)
|
|
else:
|
|
base[key] = value
|
|
return base
|
|
|
|
|
|
def build(mkdocs_yml: Path) -> None:
|
|
"""
|
|
Build the MkDocs documentation site.
|
|
|
|
This function loads the MkDocs configuration and runs the MkDocs
|
|
build command to generate the final static documentation site.
|
|
|
|
Args:
|
|
mkdocs_yml (Path):
|
|
Path to the `mkdocs.yml` configuration file.
|
|
|
|
Raises:
|
|
click.ClickException:
|
|
If the configuration file does not exist.
|
|
"""
|
|
if not mkdocs_yml.exists():
|
|
raise click.ClickException(f"mkdocs.yml not found: {mkdocs_yml}")
|
|
|
|
from mkdocs.commands.build import build as mkdocs_build
|
|
from mkdocs.config import load_config
|
|
|
|
mkdocs_build(load_config(str(mkdocs_yml)))
|
|
|
|
|
|
def serve(mkdocs_yml: Path) -> None:
|
|
"""
|
|
Start an MkDocs development server with live reload.
|
|
|
|
The server watches documentation files and automatically reloads
|
|
the site when changes are detected.
|
|
|
|
Args:
|
|
mkdocs_yml (Path):
|
|
Path to the `mkdocs.yml` configuration file.
|
|
|
|
Raises:
|
|
click.ClickException:
|
|
If the configuration file does not exist.
|
|
"""
|
|
if not mkdocs_yml.exists():
|
|
raise click.ClickException(f"mkdocs.yml not found: {mkdocs_yml}")
|
|
|
|
from mkdocs.commands.serve import serve as mkdocs_serve
|
|
|
|
mkdocs_serve(config_file=str(mkdocs_yml))
|