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

updated doc strings

Browse Source
This commit is contained in:
Vishesh 'ironeagle' Bangotra
2026-03-07 15:44:02 +05:30
parent 73b15cc3ab
commit 17d39a3e88
21 changed files with 680 additions and 330 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
docforge/nav/__init__.py
View File

@@ -1,17 +1,22 @@
"""
# Navigation Layer
Navigation layer for doc-forge.
The `docforge.nav` package manages the mapping between the logical documentation
structure and the physical files on disk.
The ``docforge.nav`` package manages the relationship between the logical
documentation structure defined by the user and the physical documentation
files generated on disk.
## Workflow
Workflow
--------
1. **Spec Definition**: Users define navigation intent in `docforge.nav.yml`.
2. **Resolution**: `resolve_nav` matches patterns in the spec to generated `.md` files.
3. **Emission**: `MkDocsNavEmitter` produces the final YAML structure for `mkdocs.yml`.
1. **Specification** – Users define navigation intent in ``docforge.nav.yml``.
2. **Resolution** – ``resolve_nav`` expands patterns and matches them against
generated Markdown files.
3. **Emission** – ``MkDocsNavEmitter`` converts the resolved structure into
the YAML navigation format required by ``mkdocs.yml``.
This abstraction allows doc-forge to support complex grouping and ordering
independently of the source code's physical layout.
This layer separates documentation organization from the underlying source
code layout, enabling flexible grouping, ordering, and navigation structures
independent of module hierarchy.
"""
from .spec import NavSpec, load_nav_spec

39
docforge/nav/mkdocs.py
View File

@@ -1,7 +1,9 @@
"""
This module provides the MkDocsNavEmitter, which converts a ResolvedNav instance
into the specific YAML-ready list structure expected by the MkDocs 'nav'
configuration.
MkDocs navigation emitter.
This module provides the ``MkDocsNavEmitter`` class, which converts a
``ResolvedNav`` instance into the navigation structure required by the
MkDocs ``nav`` configuration.
"""
from pathlib import Path
@@ -12,19 +14,24 @@ from docforge.nav.resolver import ResolvedNav
class MkDocsNavEmitter:
"""
Emitter responsible for transforming a ResolvedNav into an MkDocs-compatible
navigation structure.
Emit MkDocs navigation structures from resolved navigation data.
The emitter transforms a ``ResolvedNav`` object into the YAML-compatible
list structure expected by the MkDocs ``nav`` configuration field.
"""
def emit(self, nav: ResolvedNav) -> List[Dict[str, Any]]:
"""
Generate a list of navigation entries for mkdocs.yml.
Generate a navigation structure for ``mkdocs.yml``.
Args:
nav: The resolved navigation data.
nav: Resolved navigation data describing documentation groups
and their associated Markdown files.
Returns:
A list of dictionary mappings representing the MkDocs navigation.
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]] = []
@@ -45,16 +52,18 @@ class MkDocsNavEmitter:
def _to_relative(self, path: Path, docs_root: Path | None) -> str:
"""
Convert a filesystem path to a path relative to the documentation root.
This handles both absolute and relative filesystem paths, ensuring the
output is compatible with MkDocs navigation requirements.
Convert a filesystem path into a documentation-relative path.
This method normalizes paths so they can be used in MkDocs navigation.
It handles both absolute and relative filesystem paths and ensures the
resulting path is relative to the documentation root.
Args:
path: The path to convert.
docs_root: The root directory for documentation.
path: Filesystem path to convert.
docs_root: Root directory of the documentation sources.
Returns:
A string representing the relative POSIX-style path.
POSIX-style path relative to the documentation root.
"""
if docs_root and path.is_absolute():
try:
@@ -67,6 +76,6 @@ class MkDocsNavEmitter:
docs_root_str = docs_root.as_posix()
if path_str.startswith(docs_root_str + "/"):
return path_str[len(docs_root_str) + 1:]
# Fallback for other cases
return path.as_posix().split("/docs/", 1)[-1]

60
docforge/nav/resolver.py
View File

@@ -1,7 +1,8 @@
"""
This module contains the logic for resolving a NavSpec against the physical
filesystem. It expands globs and validates that all referenced documents
actually exist on disk.
Navigation resolution utilities.
This module resolves a ``NavSpec`` against the filesystem by expanding glob
patterns and validating that referenced documentation files exist.
"""
from pathlib import Path
@@ -14,12 +15,15 @@ from docforge.nav.spec import NavSpec
class ResolvedNav:
"""
Represents a navigation structure where all patterns and paths have been
resolved against the actual filesystem contents.
Resolved navigation structure.
A ``ResolvedNav`` represents navigation data after glob patterns have been
expanded and paths validated against the filesystem.
Attributes:
home: Resolved relative path to the home page.
groups: Mapping of group titles to lists of absolute or relative Path objects.
home: Relative path to the documentation home page.
groups: Mapping of navigation group titles to lists of resolved
documentation file paths.
"""
def __init__(
@@ -32,9 +36,9 @@ class ResolvedNav:
Initialize a ResolvedNav instance.
Args:
home: The relative path to the project home page.
groups: A mapping of group names to their resolved filesystem paths.
docs_root: The root documentation directory.
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.
"""
self.home = home
self.groups = groups
@@ -42,15 +46,20 @@ class ResolvedNav:
def all_files(self) -> Iterable[Path]:
"""
Get an iterable of all resolved files in the navigation structure.
Iterate over all files referenced by the navigation structure.
Returns:
An iterable of Path objects.
An iterable of ``Path`` objects representing documentation files.
Raises:
RuntimeError: If the home page is defined but the documentation
root is not available for resolution.
"""
if self.home:
if self._docs_root is None:
raise RuntimeError("docs_root is required to resolve home path")
yield self._docs_root / self.home
for paths in self.groups.values():
for p in paths:
yield p
@@ -61,34 +70,37 @@ def resolve_nav(
docs_root: Path,
) -> ResolvedNav:
"""
Create a ResolvedNav by processing a NavSpec against the filesystem.
This expands globs and validates the existence of referenced files.
Resolve a navigation specification against the filesystem.
The function expands glob patterns defined in a ``NavSpec`` and verifies
that referenced documentation files exist within the documentation root.
Args:
spec: The navigation specification to resolve.
docs_root: The root directory for documentation files.
spec: Navigation specification describing documentation layout.
docs_root: Root directory containing documentation Markdown files.
Returns:
A ResolvedNav instance.
A ``ResolvedNav`` instance containing validated navigation paths.
Raises:
FileNotFoundError: If a pattern doesn't match any files or the docs_root doesn't exist.
FileNotFoundError: If the documentation root does not exist or a
navigation pattern does not match any files.
"""
if not docs_root.exists():
raise FileNotFoundError(docs_root)
def resolve_pattern(pattern: str) -> List[Path]:
"""
Resolve a single glob pattern relative to the docs_root.
Resolve a glob pattern relative to the documentation root.
Args:
pattern: The glob pattern to resolve.
pattern: Glob pattern used to match documentation files.
Returns:
A sorted list of matching Path objects.
A sorted list of matching ``Path`` objects.
Raises:
FileNotFoundError: If the pattern doesn't match any files.
FileNotFoundError: If the pattern does not match any files.
"""
full = docs_root / pattern
matches = sorted(
@@ -100,7 +112,7 @@ def resolve_nav(
return matches
# Resolve home
# Resolve home page
home: str | None = None
if spec.home:
home_path = docs_root / spec.home
@@ -108,7 +120,7 @@ def resolve_nav(
raise FileNotFoundError(spec.home)
home = spec.home
# Resolve groups
# Resolve navigation groups
resolved_groups: Dict[str, List[Path]] = {}
for group, patterns in spec.groups.items():

57
docforge/nav/spec.py
View File

@@ -1,7 +1,9 @@
"""
This module defines the NavSpec class, which represents the user's intent for
documentation navigation as defined in a YAML specification (usually
docforge.nav.yml).
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``).
"""
from pathlib import Path
@@ -12,11 +14,16 @@ import yaml
class NavSpec:
"""
Parsed representation of the docforge navigation specification file.
Parsed representation of a navigation specification.
A ``NavSpec`` describes the intended documentation navigation layout before
it is resolved against the filesystem.
Attributes:
home: Path to the home document (e.g., 'index.md').
groups: Mapping of group titles to lists of path patterns/globs.
home: Relative path to the documentation home page (for example
``index.md``).
groups: Mapping of navigation group titles to lists of file patterns
or glob expressions.
"""
def __init__(
@@ -25,11 +32,12 @@ class NavSpec:
groups: Dict[str, List[str]],
) -> None:
"""
Initialize a NavSpec.
Initialize a NavSpec instance.
Args:
home: The path to the home document.
groups: A mapping of group names to lists of path patterns (globs).
home: Relative path to the home document.
groups: Mapping of group names to lists of path patterns
(glob expressions).
"""
self.home = home
self.groups = groups
@@ -37,17 +45,18 @@ class NavSpec:
@classmethod
def load(cls, path: Path) -> "NavSpec":
"""
Load a NavSpec from a YAML file.
Load a navigation specification from a YAML file.
Args:
path: The filesystem path to the YAML file.
path: Filesystem path to the navigation specification file.
Returns:
A NavSpec instance.
A ``NavSpec`` instance representing the parsed configuration.
Raises:
FileNotFoundError: If the path does not exist.
ValueError: If the file content is not a valid NavSpec mapping.
FileNotFoundError: If the specified file does not exist.
ValueError: If the file contents are not a valid navigation
specification.
"""
if not path.exists():
raise FileNotFoundError(path)
@@ -78,33 +87,45 @@ class NavSpec:
def all_patterns(self) -> List[str]:
"""
Get all path patterns referenced in the specification.
Return all path patterns referenced by the specification.
Returns:
A list of all patterns (home plus all groups).
A list containing the home document (if defined) and all
group pattern entries.
"""
patterns: List[str] = []
if self.home:
patterns.append(self.home)
for items in self.groups.values():
patterns.extend(items)
return patterns
def load_nav_spec(path: Path) -> NavSpec:
"""
Utility function to load a NavSpec from a file.
Load a navigation specification file.
This helper function reads a YAML navigation file and constructs a
corresponding ``NavSpec`` instance.
Args:
path: Path to the navigation specification file.
Returns:
A loaded NavSpec instance.
A ``NavSpec`` instance representing the parsed specification.
Raises:
FileNotFoundError: If the specification file does not exist.
ValueError: If the YAML structure is invalid.
"""
if not path.exists():
raise FileNotFoundError(path)
data = yaml.safe_load(path.read_text(encoding="utf-8"))
if not isinstance(data, dict):
raise ValueError("Nav spec must be a YAML mapping")