added docs strings

docforge/nav/__init__.py

@@ -1,3 +1,19 @@
+"""
+# Navigation Layer
+
+The `docforge.nav` package manages the mapping between the logical documentation
+structure and the physical files on disk.
+
+## 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`.
+
+This abstraction allows doc-forge to support complex grouping and ordering
+independently of the source code's physical layout.
+"""
+
 from .spec import NavSpec, load_nav_spec
 from .resolver import ResolvedNav, resolve_nav
 from .mkdocs import MkDocsNavEmitter

docforge/nav/mkdocs.py

@@ -1,3 +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.
+"""
+
 from pathlib import Path
 from typing import List, Dict, Any
 
@@ -5,9 +11,21 @@ from docforge.nav.resolver import ResolvedNav
 
 
 class MkDocsNavEmitter:
-    """Emit MkDocs-compatible nav structures."""
+    """
+    Emitter responsible for transforming a ResolvedNav into an MkDocs-compatible
+    navigation structure.
+    """
 
     def emit(self, nav: ResolvedNav) -> List[Dict[str, Any]]:
+        """
+        Generate a list of navigation entries for mkdocs.yml.
+
+        Args:
+            nav: The resolved navigation data.
+
+        Returns:
+            A list of dictionary mappings representing the MkDocs navigation.
+        """
         result: List[Dict[str, Any]] = []
 
         # Home entry (semantic path)
@@ -27,7 +45,16 @@ class MkDocsNavEmitter:
 
     def _to_relative(self, path: Path, docs_root: Path | None) -> str:
         """
-        Convert a filesystem path to a docs-relative path.
+        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.
+
+        Args:
+            path: The path to convert.
+            docs_root: The root directory for documentation.
+
+        Returns:
+            A string representing the relative POSIX-style path.
         """
         if docs_root and path.is_absolute():
             try:

docforge/nav/resolver.py

@@ -1,3 +1,9 @@
+"""
+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.
+"""
+
 from pathlib import Path
 from typing import Dict, Iterable, List
 
@@ -7,17 +13,40 @@ 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.
+
+    Attributes:
+        home: Resolved relative path to the home page.
+        groups: Mapping of group titles to lists of absolute or relative Path objects.
+    """
+
     def __init__(
         self,
         home: str | None,
         groups: Dict[str, List[Path]],
         docs_root: Path | None = None,
     ) -> None:
+        """
+        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.
+        """
         self.home = home
         self.groups = groups
         self._docs_root = docs_root
 
     def all_files(self) -> Iterable[Path]:
+        """
+        Get an iterable of all resolved files in the navigation structure.
+
+        Returns:
+            An iterable of Path objects.
+        """
         if self.home:
             if self._docs_root is None:
                 raise RuntimeError("docs_root is required to resolve home path")
@@ -31,6 +60,20 @@ def resolve_nav(
     spec: NavSpec,
     docs_root: Path,
 ) -> ResolvedNav:
+    """
+    Create a ResolvedNav by processing a NavSpec against the filesystem.
+    This expands globs and validates the existence of referenced files.
+
+    Args:
+        spec: The navigation specification to resolve.
+        docs_root: The root directory for documentation files.
+
+    Returns:
+        A ResolvedNav instance.
+
+    Raises:
+        FileNotFoundError: If a pattern doesn't match any files or the docs_root doesn't exist.
+    """
     if not docs_root.exists():
         raise FileNotFoundError(docs_root)
 

docforge/nav/spec.py

@@ -1,3 +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).
+"""
+
 from pathlib import Path
 from typing import Dict, List, Optional
 
@@ -5,18 +11,44 @@ import yaml
 
 
 class NavSpec:
-    """Parsed representation of docforge.nav.yml."""
+    """
+    Parsed representation of the docforge navigation specification file.
+
+    Attributes:
+        home: Path to the home document (e.g., 'index.md').
+        groups: Mapping of group titles to lists of path patterns/globs.
+    """
 
     def __init__(
         self,
         home: Optional[str],
         groups: Dict[str, List[str]],
     ) -> None:
+        """
+        Initialize a NavSpec.
+
+        Args:
+            home: The path to the home document.
+            groups: A mapping of group names to lists of path patterns (globs).
+        """
         self.home = home
         self.groups = groups
 
     @classmethod
     def load(cls, path: Path) -> "NavSpec":
+        """
+        Load a NavSpec from a YAML file.
+
+        Args:
+            path: The filesystem path to the YAML file.
+
+        Returns:
+            A NavSpec instance.
+
+        Raises:
+            FileNotFoundError: If the path does not exist.
+            ValueError: If the file content is not a valid NavSpec mapping.
+        """
         if not path.exists():
             raise FileNotFoundError(path)
 
@@ -45,6 +77,12 @@ class NavSpec:
         return cls(home=home, groups=groups)
 
     def all_patterns(self) -> List[str]:
+        """
+        Get all path patterns referenced in the specification.
+
+        Returns:
+            A list of all patterns (home plus all groups).
+        """
         patterns: List[str] = []
         if self.home:
             patterns.append(self.home)
@@ -54,6 +92,15 @@ class NavSpec:
 
 
 def load_nav_spec(path: Path) -> NavSpec:
+    """
+    Utility function to load a NavSpec from a file.
+
+    Args:
+        path: Path to the navigation specification file.
+
+    Returns:
+        A loaded NavSpec instance.
+    """
     if not path.exists():
         raise FileNotFoundError(path)