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

docs: bring docforge docstrings and wiki to GSDFC standard

Browse Source 
- 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
This commit is contained in:
Vishesh 'ironeagle' Bangotra
2026-09-12 13:12:51 +05:30
parent 8c6c46caf2
commit 582b6809a0
82 changed files with 1467 additions and 703 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
docforge/cli/api_utils.py
View File

@@ -35,7 +35,8 @@ 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.
spec_path (Path):
Path to the OpenAPI JSON specification file.
Returns:
dict:
@@ -68,7 +69,8 @@ def derive_metadata(spec: dict) -> OpenAPIMetadata:
Derive MkDocs site metadata from an OpenAPI spec ``info`` block.
Args:
spec: Parsed OpenAPI specification.
spec (dict):
Parsed OpenAPI specification.
Returns:
OpenAPIMetadata:
@@ -97,8 +99,10 @@ def generate_api_sources(spec: dict, docs_dir: Path) -> None:
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
spec (dict):
Parsed OpenAPI specification.
docs_dir (Path):
Directory (for example ``docs/api``) where the swagger
sources are written.
"""
docs_dir.mkdir(parents=True, exist_ok=True)

40
docforge/cli/commands.py
View File

@@ -4,6 +4,15 @@
Command definitions for the doc-forge CLI.
Provides the CLI structure using Click, including build, serve, and tree commands.
---
Notes:
- The `build` command validates requested modes before generating anything.
- `--mkdocs`, `--api`, and `--wiki` share a single MkDocs build; `--mcp`
generates a machine-readable bundle independently.
---
"""
from pathlib import Path
@@ -12,6 +21,7 @@ import click
from docforge.cli import api_utils, mcp_utils, mkdocs_utils
from docforge.loaders import GriffeLoader
from docforge.models import DocObject
@click.group()
@@ -99,9 +109,9 @@ def build(
"""
Build documentation artifacts.
This command performs the full documentation build pipeline:
style of the selected platform, generates renderer-specific
documentation sources, and optionally builds the final output.
This command runs the full documentation pipeline: it loads Python
modules, generates renderer-specific documentation sources, and
optionally builds or serves the final output.
Depending on the selected options, the build can target:
@@ -110,6 +120,12 @@ def build(
- Hand-written wiki pages included in the MkDocs site
- MCP structured documentation resources
Notes:
- At least one of `--mcp`, `--mkdocs`, `--wiki`, or `--api` must be
provided.
- `--mkdocs`, `--api`, and `--wiki` are combined into a single MkDocs
build, while `--mcp` emits a machine-readable bundle.
Args:
mcp (bool):
Enable MCP documentation generation.
@@ -126,16 +142,16 @@ def build(
module_is_source (bool):
Treat the specified module directory as the project root.
module (Optional[str]):
module (str | None):
Python module import path to document.
openapi_spec (Optional[Path]):
openapi_spec (Path | None):
Path to the OpenAPI JSON specification used for API docs.
project_name (Optional[str]):
project_name (str | None):
Optional override for the project name.
site_name (Optional[str]):
site_name (str | None):
Display name for the MkDocs site.
docs_dir (Path):
@@ -147,7 +163,7 @@ def build(
nav_file (Path):
Path to the navigation specification file.
template (Optional[Path]):
template (Path | None):
Optional custom MkDocs configuration template.
mkdocs_yml (Path):
@@ -282,7 +298,7 @@ def serve(
mkdocs (bool):
Serve the MkDocs development site.
module (Optional[str]):
module (str | None):
Python module import path to serve via MCP.
mkdocs_yml (Path):
@@ -333,7 +349,7 @@ def tree(
module (str):
Python module import path to introspect.
project_name (Optional[str]):
project_name (str | None):
Optional name to display as the project root.
"""
loader = GriffeLoader()
@@ -347,7 +363,7 @@ def tree(
_print_object(obj, indent="│ ")
def _print_object(obj, indent: str) -> None:
def _print_object(obj: DocObject, indent: str) -> None:
"""
Recursively print a documentation object and its members.
@@ -355,7 +371,7 @@ def _print_object(obj, indent: str) -> None:
and prints each object with indentation to represent hierarchy.
Args:
obj:
obj (DocObject):
Documentation object to print.
indent (str):

5
docforge/cli/commands.pyi
View File

@@ -1,8 +1,9 @@
from pathlib import Path
from typing import Any
from click.core import Group
from docforge.models import DocObject
cli: Group
def build(
@@ -33,4 +34,4 @@ def tree(
module: str,
project_name: str | None,
) -> None: ...
def _print_object(obj: Any, indent: str) -> None: ...
def _print_object(obj: DocObject, indent: str) -> None: ...

12
docforge/cli/mcp_utils.py
View File

@@ -2,6 +2,16 @@
# Summary
Utilities for working with MCP in the doc-forge CLI.
---
Notes:
- `generate_resources` produces the bundle consumed by `MCPServer`:
`index.json`, `nav.json`, and per-module resources under `modules/`.
- Resource URIs use the `docs://` scheme: `docs://index`, `docs://nav`,
and `docs://modules/{module}`.
---
"""
from pathlib import Path
@@ -26,7 +36,7 @@ def generate_resources(module: str, project_name: str | None, out_dir: Path) ->
Python module import path used as the entry point for
documentation generation.
project_name (Optional[str]):
project_name (str | None):
Optional override for the project name used in generated
documentation metadata.

46
docforge/cli/mkdocs_utils.py
View File

@@ -2,6 +2,15 @@
# 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
@@ -44,14 +53,14 @@ def generate_sources(
docs_dir (Path):
Directory where the generated Markdown files will be written.
project_name (Optional[str]):
project_name (str | None):
Optional override for the project name used in documentation metadata.
module_is_source (Optional[bool]):
module_is_source (bool | None):
If True, treat the specified module directory as the project root
rather than a nested module.
readme_dir (Optional[Path]):
readme_dir (Path | None):
Directory where the generated README.md should be written. If not
provided, defaults to the parent of ``docs_dir``.
"""
@@ -105,7 +114,7 @@ def generate_config(
nav_file (Path):
Path to the `docforge.nav.yml` navigation specification.
template (Optional[Path]):
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.
@@ -116,19 +125,19 @@ def generate_config(
site_name (str):
Display name for the generated documentation site.
modes (Optional[Iterable[str]]):
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 (Optional[str]):
site_description (str | None):
Optional site description written into the configuration.
site_author (Optional[str]):
site_author (str | None):
Optional site author written into the configuration.
wiki_dir (Optional[Path]):
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
@@ -186,13 +195,13 @@ def _load_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``).
contributed by each enabled mode (``lib``, ``api``, or ``wiki``).
Args:
template (Optional[Path]):
template (Path | None):
Optional fully custom template that replaces the built-ins.
modes (Optional[Iterable[str]]):
modes (Iterable[str] | None):
Documentation modes whose template fragments should be merged.
Returns:
@@ -237,7 +246,8 @@ def _item_name(item: object) -> str:
first key. This is used to deduplicate plugin and extension lists.
Args:
item: List entry, either a string or a single-key mapping.
item (object):
List entry, either a string or a single-key mapping.
Returns:
str:
@@ -253,8 +263,10 @@ 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.
base (list):
Existing list entries.
added (list):
Entries to append when not already present.
Returns:
list:
@@ -279,8 +291,10 @@ def _deep_merge(base: dict, part: dict) -> dict:
the fragment override the base.
Args:
base: Configuration being built up.
part: Template fragment to merge into the base.
base (dict):
Configuration being built up.
part (dict):
Template fragment to merge into the base.
Returns:
dict: