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

27
docforge/nav/mkdocs.py
View File

@@ -4,6 +4,14 @@ MkDocs navigation emitter.
This module provides the ``MkDocsNavEmitter`` class, which converts a
``ResolvedNav`` instance into the navigation structure required by the
MkDocs ``nav`` configuration.
---
Notes:
- The emitted structure is a list of dictionaries, one per top-level nav
entry, matching the MkDocs ``nav`` YAML format.
---
"""
from pathlib import Path
@@ -25,13 +33,15 @@ class MkDocsNavEmitter:
Generate a navigation structure for ``mkdocs.yml``.
Args:
nav: Resolved navigation data describing documentation groups
nav (ResolvedNav):
Resolved navigation data describing documentation groups
and their associated Markdown files.
Returns:
A list of dictionaries representing the MkDocs navigation layout.
Each dictionary maps a navigation label to a page or a list of
pages.
list[dict[str, Any]]:
A list of dictionaries representing the MkDocs navigation layout.
Each dictionary maps a navigation label to a page or a list of
pages.
"""
result: list[dict[str, Any]] = []
@@ -59,11 +69,14 @@ class MkDocsNavEmitter:
resulting path is relative to the documentation root.
Args:
path: Filesystem path to convert.
docs_root: Root directory of the documentation sources.
path (Path):
Filesystem path to convert.
docs_root (Path | None):
Root directory of the documentation sources.
Returns:
POSIX-style path relative to the documentation root.
str:
POSIX-style path relative to the documentation root.
"""
if docs_root and path.is_absolute():
try:

38
docforge/nav/resolver.py
View File

@@ -3,6 +3,14 @@ Navigation resolution utilities.
This module resolves a ``NavSpec`` against the filesystem by expanding glob
patterns and validating that referenced documentation files exist.
---
Notes:
- Glob resolution is recursive and returns paths in sorted order.
- Unmatched patterns raise ``FileNotFoundError`` to fail fast on typos.
---
"""
import glob
@@ -35,9 +43,12 @@ class ResolvedNav:
Initialize a ResolvedNav instance.
Args:
home: Relative path to the home page within the documentation root.
groups: Mapping of group titles to resolved documentation file paths.
docs_root: Root directory of the documentation source files.
home (str | None):
Relative path to the home page within the documentation root.
groups (dict[str, list[Path]]):
Mapping of group titles to resolved documentation file paths.
docs_root (Path | None):
Root directory of the documentation source files.
"""
self.home = home
self.groups = groups
@@ -47,8 +58,10 @@ class ResolvedNav:
"""
Iterate over all files referenced by the navigation structure.
Returns:
An iterable of ``Path`` objects representing documentation files.
Yields:
Path:
A documentation file referenced by the navigation, including
the home page when defined.
Raises:
RuntimeError: If the home page is defined but the documentation
@@ -74,11 +87,14 @@ def resolve_nav(
that referenced documentation files exist within the documentation root.
Args:
spec: Navigation specification describing documentation layout.
docs_root: Root directory containing documentation Markdown files.
spec (NavSpec):
Navigation specification describing documentation layout.
docs_root (Path):
Root directory containing documentation Markdown files.
Returns:
A ``ResolvedNav`` instance containing validated navigation paths.
ResolvedNav:
A `ResolvedNav` instance containing validated navigation paths.
Raises:
FileNotFoundError: If the documentation root does not exist or a
@@ -92,10 +108,12 @@ def resolve_nav(
Resolve a glob pattern relative to the documentation root.
Args:
pattern: Glob pattern used to match documentation files.
pattern (str):
Glob pattern used to match documentation files.
Returns:
A sorted list of matching ``Path`` objects.
list[Path]:
A sorted list of matching `Path` objects.
Raises:
FileNotFoundError: If the pattern does not match any files.

39
docforge/nav/spec.py
View File

@@ -4,8 +4,19 @@ Navigation specification model.
This module defines the ``NavSpec`` class, which represents the navigation
structure defined by the user in the doc-forge navigation specification
(typically ``docforge.nav.yml``).
---
Notes:
- The spec file supports an optional ``icon`` mapping for MkDocs theme
customization.
- All file references in ``groups`` are relative to the documentation root.
---
"""
from __future__ import annotations
from pathlib import Path
import yaml
@@ -38,10 +49,13 @@ class NavSpec:
Initialize a NavSpec instance.
Args:
home: Relative path to the home document.
groups: Mapping of group names to lists of path patterns
home (str | None):
Relative path to the home document.
groups (dict[str, list[str]]):
Mapping of group names to lists of path patterns
(glob expressions).
icon: Optional mapping of theme icon entries applied to the
icon (dict[str, str] | None):
Optional mapping of theme icon entries applied to the
generated MkDocs configuration.
"""
self.home = home
@@ -49,15 +63,17 @@ class NavSpec:
self.icon = icon
@classmethod
def load(cls, path: Path) -> "NavSpec":
def load(cls, path: Path) -> NavSpec:
"""
Load a navigation specification from a YAML file.
Args:
path: Filesystem path to the navigation specification file.
path (Path):
Filesystem path to the navigation specification file.
Returns:
A ``NavSpec`` instance representing the parsed configuration.
NavSpec:
A ``NavSpec`` instance representing the parsed configuration.
Raises:
FileNotFoundError: If the specified file does not exist.
@@ -105,8 +121,9 @@ class NavSpec:
Return all path patterns referenced by the specification.
Returns:
A list containing the home document (if defined) and all
group pattern entries.
list[str]:
A list containing the home document (if defined) and all
group pattern entries.
"""
patterns: list[str] = []
@@ -127,10 +144,12 @@ def load_nav_spec(path: Path) -> NavSpec:
corresponding ``NavSpec`` instance.
Args:
path: Path to the navigation specification file.
path (Path):
Path to the navigation specification file.
Returns:
A ``NavSpec`` instance representing the parsed specification.
NavSpec:
A ``NavSpec`` instance representing the parsed specification.
Raises:
FileNotFoundError: If the specification file does not exist.

14
docforge/nav/wiki.py
View File

@@ -20,6 +20,7 @@ modified by doc-forge; only the navigation layout is inferred.
"""
import re
from collections.abc import Callable
from pathlib import Path
from typing import Any
@@ -46,7 +47,7 @@ def build_wiki_nav(wiki_dir: Path) -> list[dict[str, Any]]:
Path to the hand-written wiki directory, for example ``docs/wiki``.
Returns:
List[Dict[str, Any]]:
list[dict[str, Any]]:
Navigation entries compatible with the MkDocs ``nav`` configuration.
The list is empty if the wiki contains no Markdown files.
@@ -75,7 +76,10 @@ def build_wiki_nav(wiki_dir: Path) -> list[dict[str, Any]]:
return nav
def _render_entries(base_dir: Path, rel) -> list[dict[str, Any]]:
def _render_entries(
base_dir: Path,
rel: Callable[[Path], str],
) -> list[dict[str, Any]]:
"""
Render navigation entries for the children of a wiki directory.
@@ -87,11 +91,11 @@ def _render_entries(base_dir: Path, rel) -> list[dict[str, Any]]:
base_dir (Path):
Directory whose children are rendered.
rel:
rel (Callable[[Path], str]):
Callable converting a wiki file path into a docs-relative path.
Returns:
List[Dict[str, Any]]:
list[dict[str, Any]]:
Navigation entries for ``base_dir`` in natural sort order.
"""
children = sorted(
@@ -152,7 +156,7 @@ def _natural_key(name: str) -> list[object]:
Filename or directory name to key.
Returns:
List[object]:
list[object]:
Mixed list of lowercased strings and integers used for sorting.
"""
return [

32
docforge/nav/wiki.pyi
View File

@@ -1,3 +1,4 @@
from collections.abc import Callable
from pathlib import Path
from typing import Any
@@ -5,11 +6,36 @@ def build_wiki_nav(wiki_dir: Path) -> list[dict[str, Any]]:
"""
Derive an MkDocs navigation block from a wiki directory.
Args:
wiki_dir (Path):
Path to the hand-written wiki directory.
Returns:
Wiki navigation entries compatible with the MkDocs
`nav` configuration.
list[dict[str, Any]]:
Wiki navigation entries compatible with the MkDocs `nav`
configuration.
Raises:
FileNotFoundError: if the wiki directory does not exist
FileNotFoundError:
If the wiki directory does not exist.
"""
...
def _render_entries(
base_dir: Path,
rel: Callable[[Path], str],
) -> list[dict[str, Any]]:
"""
Render navigation entries for the children of a wiki directory.
Args:
base_dir (Path):
Directory whose children are rendered.
rel (Callable[[Path], str]):
Callable converting a wiki file path into a docs-relative path.
Returns:
list[dict[str, Any]]:
Navigation entries for `base_dir` in natural sort order.
"""
...