updated doc strings

docforge/nav/resolver.py

@@ -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():