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

feat: add --api OpenAPI build mode with docs/api scheme and lib-prefixed nav

Browse Source
This commit is contained in:
Vishesh 'ironeagle' Bangotra
2026-09-11 05:37:56 +05:30
parent 17e8628197
commit bacf17b930
26 changed files with 1404 additions and 174 deletions
Download Patch File Download Diff File Expand all files Collapse all files

114
docforge/cli/api_utils.py Normal file
View File

@@ -0,0 +1,114 @@
"""
# Summary
Utilities for building API documentation from an OpenAPI specification.
"""
import json
from dataclasses import dataclass
from pathlib import Path
import click
SWAGGER_SPEC_FILENAME = "openapi.json"
@dataclass
class OpenAPIMetadata:
"""
Metadata derived from the ``info`` block of an OpenAPI specification.
Attributes:
site_name: Spec title, used as the MkDocs site name.
site_description: Spec description, used as the site description.
site_author: Contact name (fallback: contact email), used as the
site author.
"""
site_name: str
site_description: str | None
site_author: str | None
def load_openapi_spec(spec_path: Path) -> dict:
"""
Load and validate an OpenAPI specification from a JSON file.
Args:
spec_path: Path to the OpenAPI JSON specification file.
Returns:
dict:
The parsed OpenAPI specification.
Raises:
click.ClickException:
If the file cannot be read or the ``info`` block is invalid.
"""
if not spec_path.exists():
raise click.ClickException(f"OpenAPI spec not found: {spec_path}")
try:
data = json.loads(spec_path.read_text(encoding="utf-8"))
except (json.JSONDecodeError, OSError) as exc:
raise click.ClickException(f"Unable to read OpenAPI spec: {exc}") from exc
if not isinstance(data, dict):
raise click.ClickException("OpenAPI spec must be a JSON mapping")
info = data.get("info")
if not isinstance(info, dict) or not isinstance(info.get("title"), str):
raise click.ClickException("OpenAPI spec missing 'info.title'")
return data
def derive_metadata(spec: dict) -> OpenAPIMetadata:
"""
Derive MkDocs site metadata from an OpenAPI spec ``info`` block.
Args:
spec: Parsed OpenAPI specification.
Returns:
OpenAPIMetadata:
Site name, description, and author derived from the spec.
"""
info = spec["info"]
contact = info.get("contact")
if isinstance(contact, dict):
author = contact.get("name") or contact.get("email")
else:
author = None
return OpenAPIMetadata(
site_name=info.get("title", ""),
site_description=info.get("description"),
site_author=author,
)
def generate_api_sources(spec: dict, docs_dir: Path) -> None:
"""
Generate swagger-enabled Markdown sources and the spec copy.
The specification is written as ``openapi.json`` inside ``docs_dir`` and
an ``index.md`` embedding the swagger UI is generated alongside it.
Args:
spec: Parsed OpenAPI specification.
docs_dir: Directory (for example ``docs/api``) where the swagger
sources are written.
"""
docs_dir.mkdir(parents=True, exist_ok=True)
spec_path = docs_dir / SWAGGER_SPEC_FILENAME
spec_json = json.dumps(spec, indent=2)
if not spec_path.exists() or spec_path.read_text(encoding="utf-8") != spec_json:
spec_path.write_text(spec_json, encoding="utf-8")
index_path = docs_dir / "index.md"
content = "# API Reference\n\n" f'<swagger-ui src="{SWAGGER_SPEC_FILENAME}"/>\n'
if not index_path.exists() or index_path.read_text(encoding="utf-8") != content:
index_path.write_text(content, encoding="utf-8")

13
docforge/cli/api_utils.pyi Normal file
View File

@@ -0,0 +1,13 @@
from dataclasses import dataclass
from pathlib import Path
from typing import Any
@dataclass
class OpenAPIMetadata:
site_name: str
site_description: str | None
site_author: str | None
def load_openapi_spec(spec_path: Path) -> dict[Any, Any]: ...
def derive_metadata(spec: dict[Any, Any]) -> OpenAPIMetadata: ...
def generate_api_sources(spec: dict[Any, Any], docs_dir: Path) -> None: ...

98
docforge/cli/commands.py
View File

@@ -10,7 +10,7 @@ from pathlib import Path
import click
from docforge.cli import mcp_utils, mkdocs_utils
from docforge.cli import api_utils, mcp_utils, mkdocs_utils
from docforge.loaders import GriffeLoader
@@ -28,19 +28,25 @@ def cli() -> None:
@cli.command()
@click.option("--mcp", is_flag=True, help="Build MCP resources")
@click.option("--mkdocs", is_flag=True, help="Build MkDocs site")
@click.option("--api", is_flag=True, help="Build API docs from an OpenAPI spec")
@click.option(
"--module-is-source",
is_flag=True,
help="Module is source folder and to be treated as root folder",
)
@click.option("--module", help="Python module to document")
@click.option(
"--openapi-spec",
type=click.Path(path_type=Path),
help="Path to the OpenAPI JSON specification",
)
@click.option("--project-name", help="Project name override")
@click.option("--site-name", help="MkDocs site name")
@click.option(
"--docs-dir",
type=click.Path(path_type=Path),
default=Path("docs/lib"),
help="Directory for MD sources",
default=Path("docs"),
help="MkDocs documentation root",
)
@click.option(
"--nav",
@@ -67,8 +73,10 @@ def cli() -> None:
def build(
mcp: bool,
mkdocs: bool,
api: bool,
module_is_source: bool,
module: str | None,
openapi_spec: Path | None,
project_name: str | None,
site_name: str | None,
docs_dir: Path,
@@ -81,14 +89,13 @@ def build(
Build documentation artifacts.
This command performs the full documentation build pipeline:
1. Introspects the Python project using Griffe
2. Generates renderer-specific documentation sources
3. Optionally builds the final documentation output
style of the selected platform, generates renderer-specific
documentation sources, and optionally builds the final output.
Depending on the selected options, the build can target:
- MkDocs static documentation sites
- MkDocs static documentation sites for library reference docs
- Swagger-enabled API docs generated from an OpenAPI spec
- MCP structured documentation resources
Args:
@@ -96,7 +103,10 @@ def build(
Enable MCP documentation generation.
mkdocs (bool):
Enable MkDocs documentation generation.
Enable MkDocs library documentation generation.
api (bool):
Enable API documentation generation from an OpenAPI spec.
module_is_source (bool):
Treat the specified module directory as the project root.
@@ -104,6 +114,9 @@ def build(
module (Optional[str]):
Python module import path to document.
openapi_spec (Optional[Path]):
Path to the OpenAPI JSON specification used for API docs.
project_name (Optional[str]):
Optional override for the project name.
@@ -111,7 +124,7 @@ def build(
Display name for the MkDocs site.
docs_dir (Path):
Directory where Markdown documentation sources will be generated.
Shared documentation root used as the MkDocs ``docs_dir``.
nav_file (Path):
Path to the navigation specification file.
@@ -129,27 +142,72 @@ def build(
click.UsageError:
If required options are missing or conflicting.
"""
if not mcp and not mkdocs:
raise click.UsageError("Must specify either --mcp or --mkdocs")
if not mcp and not mkdocs and not api:
raise click.UsageError("Must specify either --mcp, --mkdocs, or --api")
if api:
if not openapi_spec:
raise click.UsageError("--openapi-spec is required for API build")
if site_name and not mkdocs:
raise click.UsageError(
"--site-name cannot be overridden for API build; "
"the OpenAPI spec provides the site name"
)
if (mkdocs or mcp) and not module:
raise click.UsageError(
"--module is required for MkDocs build"
if mkdocs
else "--module is required for MCP build"
)
spec: dict | None = None
if api:
spec = api_utils.load_openapi_spec(openapi_spec)
if mkdocs:
if not module:
raise click.UsageError("--module is required for MkDocs build")
if not site_name:
site_name = module
click.echo(f"Generating MkDocs sources in {docs_dir}...")
lib_dir = docs_dir / "lib"
click.echo(f"Generating MkDocs sources in {lib_dir}...")
mkdocs_utils.generate_sources(
module,
docs_dir,
lib_dir,
project_name,
module_is_source,
readme_dir=mkdocs_yml.parent,
)
if api:
api_dir = docs_dir / "api"
click.echo(f"Generating API sources in {api_dir}...")
api_utils.generate_api_sources(spec, api_dir)
if mkdocs or api:
modes: list[str] = []
if mkdocs:
modes.append("lib")
if api:
modes.append("api")
site_description: str | None = None
site_author: str | None = None
effective_site_name = site_name or module
if api:
metadata = api_utils.derive_metadata(spec)
effective_site_name = metadata.site_name
site_description = metadata.site_description
site_author = metadata.site_author
click.echo(f"Generating MkDocs config {mkdocs_yml}...")
mkdocs_utils.generate_config(
docs_dir, nav_file, template, mkdocs_yml, site_name
docs_dir,
nav_file,
template,
mkdocs_yml,
effective_site_name,
modes=modes,
site_description=site_description,
site_author=site_author,
)
click.echo("Running MkDocs build...")

2
docforge/cli/commands.pyi
View File

@@ -8,8 +8,10 @@ cli: Group
def build(
mcp: bool,
mkdocs: bool,
api: bool,
module_is_source: bool,
module: str | None,
openapi_spec: Path | None,
project_name: str | None,
site_name: str | None,
docs_dir: Path,

169
docforge/cli/mkdocs_utils.py
View File

@@ -5,6 +5,7 @@ Utilities for working with MkDocs in the doc-forge CLI.
"""
import os
from collections.abc import Iterable
from importlib import resources
from pathlib import Path
@@ -74,6 +75,9 @@ def generate_config(
template: Path | None,
out: Path,
site_name: str,
modes: Iterable[str] | None = None,
site_description: str | None = None,
site_author: str | None = None,
) -> None:
"""
Generate an `mkdocs.yml` configuration file.
@@ -82,16 +86,21 @@ def generate_config(
with a navigation structure derived from the docforge navigation
specification.
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.
Args:
docs_dir (Path):
Directory containing generated documentation Markdown files.
Shared documentation root used as the MkDocs ``docs_dir``.
nav_file (Path):
Path to the `docforge.nav.yml` navigation specification.
template (Optional[Path]):
Optional path to a custom MkDocs configuration template. If not
provided, a built-in template will be used.
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.
@@ -99,6 +108,17 @@ def generate_config(
site_name (str):
Display name for the generated documentation site.
modes (Optional[Iterable[str]]):
Documentation modes to enable. Each mode contributes its own
built-in template fragment (for example ``lib`` or ``api``),
merged on top of the shared ``mkdocs.common.yml`` template.
site_description (Optional[str]):
Optional site description written into the configuration.
site_author (Optional[str]):
Optional site author written into the configuration.
Raises:
click.FileError:
If the navigation specification or template file cannot be found.
@@ -110,26 +130,145 @@ def generate_config(
resolved = resolve_nav(spec, docs_dir)
nav_block = MkDocsNavEmitter().emit(resolved)
# Load template
if template is not None:
if not template.exists():
raise click.FileError(str(template), hint="Template not found")
data = yaml.safe_load(template.read_text(encoding="utf-8"))
else:
text = (
resources.files("docforge.templates")
.joinpath("mkdocs.sample.yml")
.read_text(encoding="utf-8")
)
data = yaml.safe_load(text)
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.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`` or ``api``).
Args:
template (Optional[Path]):
Optional fully custom template that replaces the built-ins.
modes (Optional[Iterable[str]]):
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: 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: Existing list entries.
added: 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: Configuration being built up.
part: 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.

11
docforge/cli/mkdocs_utils.pyi
View File

@@ -1,3 +1,4 @@
from collections.abc import Iterable
from pathlib import Path
def generate_sources(
@@ -5,9 +6,17 @@ def generate_sources(
docs_dir: Path,
project_name: str | None = None,
module_is_source: bool | None = None,
readme_dir: Path | None = None,
) -> None: ...
def generate_config(
docs_dir: Path, nav_file: Path, template: Path | None, out: Path, site_name: str
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,
) -> None: ...
def build(mkdocs_yml: Path) -> None: ...
def serve(mkdocs_yml: Path) -> None: ...