refactor: rename loader/model packages to loaders/models

- Rename docforge.loader → docforge.loaders and docforge.model → docforge.models
- Update all imports, type stubs, CLI, tests, and documentation references
- Align MkDocs navigation and docforge.nav.yml with new package structure
- Adjust module docstrings and comments for consistency with pluralized naming

docforge/models/__init__.py

@@ -0,0 +1,25 @@
+"""
+# Model Layer
+
+The `docforge.models` package provides the core data structures used to represent
+Python source code in a documentation-focused hierarchy.
+
+## Key Components
+
+- **Project**: The root container for all documented modules.
+- **Module**: Represents a Python module or package, containing members.
+- **DocObject**: A recursive structure for classes, functions, and attributes.
+
+These classes are designed to be renderer-agnostic, allowing the same internal
+representation to be transformed into various output formats (currently MkDocs).
+"""
+
+from .project import Project
+from .module import Module
+from .object import DocObject
+
+__all__ = [
+    "Project",
+    "Module",
+    "DocObject",
+]

docforge/models/__init__.pyi

@@ -0,0 +1,9 @@
+from .project import Project
+from .module import Module
+from .object import DocObject
+
+__all__ = [
+    "Project",
+    "Module",
+    "DocObject",
+]

docforge/models/module.py

@@ -0,0 +1,66 @@
+"""
+This module defines the Module class, which represents a Python module or package
+in the doc-forge documentation models. It acts as a container for top-level
+documented objects.
+"""
+
+from typing import Dict, Iterable, Optional
+
+from docforge.models.object import DocObject
+
+
+class Module:
+    """
+    Represents a documented Python module or package.
+
+    Attributes:
+        path: Dotted import path of the module.
+        docstring: Module-level docstring content.
+        members: Dictionary mapping object names to their DocObject representations.
+    """
+
+    def __init__(
+        self,
+        path: str,
+        docstring: Optional[str] = None,
+    ) -> None:
+        """
+        Initialize a new Module.
+
+        Args:
+            path: The dotted path of the module.
+            docstring: The module's docstring, if any.
+        """
+        self.path = path
+        self.docstring = docstring
+        self.members: Dict[str, DocObject] = {}
+
+    def add_object(self, obj: DocObject) -> None:
+        """
+        Add a documented object to the module.
+
+        Args:
+            obj: The object to add.
+        """
+        self.members[obj.name] = obj
+
+    def get_object(self, name: str) -> DocObject:
+        """
+        Retrieve a member object by name.
+
+        Args:
+            name: The name of the object.
+
+        Returns:
+            The requested DocObject.
+        """
+        return self.members[name]
+
+    def get_all_objects(self) -> Iterable[DocObject]:
+        """
+        Get all top-level objects in the module.
+
+        Returns:
+            An iterable of DocObject instances.
+        """
+        return self.members.values()

docforge/models/module.pyi

@@ -0,0 +1,23 @@
+from typing import Dict, Iterable, Optional
+
+from docforge.models.object import DocObject
+
+
+class Module:
+    """Represents a documented Python module."""
+
+    path: str
+    docstring: Optional[str]
+    members: Dict[str, DocObject]
+
+    def __init__(
+        self,
+        path: str,
+        docstring: Optional[str] = ...,
+    ) -> None: ...
+
+    def add_object(self, obj: DocObject) -> None: ...
+
+    def get_object(self, name: str) -> DocObject: ...
+
+    def get_all_objects(self) -> Iterable[DocObject]: ...

docforge/models/object.py

@@ -0,0 +1,76 @@
+"""
+This module defines the DocObject class, the fundamental recursive unit of the
+doc-forge documentation models. A DocObject represents a single Python entity
+(class, function, method, or attribute) and its nested members.
+"""
+
+from typing import Dict, Iterable, Optional
+
+
+class DocObject:
+    """
+    Represents a documented Python object (class, function, method, etc.).
+
+    Attributes:
+        name: Local name of the object.
+        kind: Type of object (e.g., 'class', 'function', 'attribute').
+        path: Full dotted import path to the object.
+        signature: Callable signature, if applicable.
+        docstring: Raw docstring content extracted from the source.
+        members: Dictionary mapping member names to their DocObject representations.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        kind: str,
+        path: str,
+        signature: Optional[str] = None,
+        docstring: Optional[str] = None,
+    ) -> None:
+        """
+        Initialize a new DocObject.
+
+        Args:
+            name: The local name of the object.
+            kind: The kind of object (e.g., 'class', 'function').
+            path: The full dotted path to the object.
+            signature: The object's signature (for callable objects).
+            docstring: The object's docstring, if any.
+        """
+        self.name = name
+        self.kind = kind
+        self.path = path
+        self.signature = signature
+        self.docstring = docstring
+        self.members: Dict[str, 'DocObject'] = {}
+
+    def add_member(self, obj: 'DocObject') -> None:
+        """
+        Add a child member to this object (e.g., a method to a class).
+
+        Args:
+            obj: The child DocObject to add.
+        """
+        self.members[obj.name] = obj
+
+    def get_member(self, name: str) -> 'DocObject':
+        """
+        Retrieve a child member by name.
+
+        Args:
+            name: The name of the member.
+
+        Returns:
+            The requested DocObject.
+        """
+        return self.members[name]
+
+    def get_all_members(self) -> Iterable['DocObject']:
+        """
+        Get all members of this object.
+
+        Returns:
+            An iterable of child DocObject instances.
+        """
+        return self.members.values()

docforge/models/object.pyi

@@ -0,0 +1,27 @@
+from typing import Dict, Iterable, Optional
+
+
+class DocObject:
+    """Represents a documented Python object."""
+
+    name: str
+    kind: str
+    path: str
+    signature: Optional[str]
+    docstring: Optional[str]
+    members: Dict[str, "DocObject"]
+
+    def __init__(
+        self,
+        name: str,
+        kind: str,
+        path: str,
+        signature: Optional[str] = ...,
+        docstring: Optional[str] = ...,
+    ) -> None: ...
+
+    def add_member(self, obj: "DocObject") -> None: ...
+
+    def get_member(self, name: str) -> "DocObject": ...
+
+    def get_all_members(self) -> Iterable["DocObject"]: ...

docforge/models/project.py

@@ -0,0 +1,67 @@
+"""
+This module defines the Project class, the top-level container for a documented
+project. It aggregates multiple Module instances into a single named entity.
+"""
+
+from typing import Dict, Iterable
+
+from docforge.models.module import Module
+
+
+class Project:
+    """
+    Represents a documentation project, serving as a container for modules.
+
+    Attributes:
+        name: Name of the project.
+        modules: Dictionary mapping module paths to Module instances.
+    """
+
+    def __init__(self, name: str) -> None:
+        """
+        Initialize a new Project.
+
+        Args:
+            name: The name of the project.
+        """
+        self.name = name
+        self.modules: Dict[str, Module] = {}
+
+    def add_module(self, module: Module) -> None:
+        """
+        Add a module to the project.
+
+        Args:
+            module: The module to add.
+        """
+        self.modules[module.path] = module
+
+    def get_module(self, path: str) -> Module:
+        """
+        Retrieve a module by its dotted path.
+
+        Args:
+            path: The dotted path of the module (e.g., 'pkg.mod').
+
+        Returns:
+            The requested Module.
+        """
+        return self.modules[path]
+
+    def get_all_modules(self) -> Iterable[Module]:
+        """
+        Get all modules in the project.
+
+        Returns:
+            An iterable of Module objects.
+        """
+        return self.modules.values()
+
+    def get_module_list(self) -> list[str]:
+        """
+        Get the list of all module dotted paths.
+
+        Returns:
+            A list of module paths.
+        """
+        return list(self.modules.keys())

docforge/models/project.pyi

@@ -0,0 +1,20 @@
+from typing import Dict, Iterable
+
+from docforge.models.module import Module
+
+
+class Project:
+    """Represents a documentation project."""
+
+    name: str
+    modules: Dict[str, Module]
+
+    def __init__(self, name: str) -> None: ...
+
+    def add_module(self, module: Module) -> None: ...
+
+    def get_module(self, path: str) -> Module: ...
+
+    def get_all_modules(self) -> Iterable[Module]: ...
+
+    def get_module_list(self) -> list[str]: ...