feat: add --api OpenAPI build mode with docs/api scheme and lib-prefixed nav

docforge/nav/spec.py

@@ -23,12 +23,16 @@ class NavSpec:
             ``index.md``).
         groups: Mapping of navigation group titles to lists of file patterns
             or glob expressions.
+        icon: Optional mapping of theme icon entries (for example
+            ``{"logo": "material/code-tags"}``) injected into the MkDocs
+            theme as ``theme.icon``.
     """
 
     def __init__(
         self,
         home: str | None,
         groups: dict[str, list[str]],
+        icon: dict[str, str] | None = None,
     ) -> None:
         """
         Initialize a NavSpec instance.
@@ -37,9 +41,12 @@ class NavSpec:
             home: Relative path to the home document.
             groups: Mapping of group names to lists of path patterns
                 (glob expressions).
+            icon: Optional mapping of theme icon entries applied to the
+                generated MkDocs configuration.
         """
         self.home = home
         self.groups = groups
+        self.icon = icon
 
     @classmethod
     def load(cls, path: Path) -> "NavSpec":
@@ -67,6 +74,7 @@ class NavSpec:
 
         home = data.get("home")
         groups = data.get("groups", {})
+        icon = data.get("icon")
 
         if home is not None and not isinstance(home, str):
             raise ValueError("home must be a string")
@@ -82,7 +90,15 @@ class NavSpec:
             ):
                 raise ValueError(f"group '{key}' must be a list of strings")
 
-        return cls(home=home, groups=groups)
+        if icon is not None and (
+            not isinstance(icon, dict)
+            or not all(
+                isinstance(k, str) and isinstance(v, str) for k, v in icon.items()
+            )
+        ):
+            raise ValueError("icon must be a mapping of strings")
+
+        return cls(home=home, groups=groups, icon=icon)
 
     def all_patterns(self) -> list[str]:
         """
@@ -131,4 +147,5 @@ def load_nav_spec(path: Path) -> NavSpec:
     return NavSpec(
         home=data.get("home"),
         groups=data.get("groups", {}),
+        icon=data.get("icon"),
     )