Models

docforge.models

Summary

Model layer for doc-forge.

The docforge.models package defines the core data structures used to represent Python source code as a structured documentation model.

---

Overview

The model layer forms the central intermediate representation used throughout doc-forge. Python modules and objects discovered during introspection are converted into a hierarchy of documentation models that can later be rendered into different documentation formats.

Key components:

• Project – Root container representing an entire documented codebase.
• Module – Representation of a Python module or package containing documented members.
• DocObject – Recursive structure representing Python objects such as classes, functions, methods, and attributes.

These models are intentionally renderer-agnostic, allowing the same documentation structure to be transformed into multiple output formats (e.g., MkDocs, MCP, or other renderers).

---

Classes

DocObject

DocObject(name: str, kind: str, path: str, signature: Optional[str] = None, docstring: Optional[str] = None)

Representation of a documented Python object.

A DocObject models a single Python entity discovered during introspection. Objects may contain nested members, allowing the structure of modules, classes, and other containers to be represented recursively.

Attributes:

Name	Type	Description
name	str	Local name of the object.
kind	str	Type of object (for example class, function, method, or attribute).
path	str	Fully qualified dotted path to the object.
signature	Optional[str]	Callable signature if the object represents a callable.
docstring	Optional[str]	Raw docstring text extracted from the source code.
members	Dict[str, DocObject]	Mapping of member names to child DocObject instances.

Initialize a DocObject instance.

Parameters:

Name	Type	Description	Default
name	str	Local name of the object.	required
kind	str	Object type identifier (for example class or function).	required
path	str	Fully qualified dotted path of the object.	required
signature	Optional[str]	Callable signature if applicable.	None
docstring	Optional[str]	Documentation string associated with the object.	None

Functions

add_member

add_member(obj: DocObject) -> None

Add a child documentation object.

This is typically used when attaching methods to classes or nested objects to their parent containers.

Parameters:

Name	Type	Description	Default
obj	DocObject	Documentation object to add as a member.	required

get_all_members

get_all_members() -> Iterable[DocObject]

Return all child members of the object.

Returns:

Type	Description
Iterable[DocObject]	Iterable[DocObject]: An iterable of DocObject instances representing nested members.

get_member

get_member(name: str) -> DocObject

Retrieve a member object by name.

Parameters:

Name	Type	Description	Default
name	str	Name of the member to retrieve.	required

Returns:

Name	Type	Description
DocObject	DocObject	The corresponding DocObject instance.

Raises:

Type	Description
KeyError	If the member does not exist.

Module

Module(path: str, docstring: Optional[str] = None)

Representation of a documented Python module or package.

A Module stores metadata about the module itself and maintains a collection of top-level documentation objects discovered during introspection.

Attributes:

Name	Type	Description
path	str	Dotted import path of the module.
docstring	Optional[str]	Module-level documentation string, if present.
members	Dict[str, DocObject]	Mapping of object names to their corresponding DocObject representations.

Initialize a Module instance.

Parameters:

Name	Type	Description	Default
path	str	Dotted import path identifying the module.	required
docstring	Optional[str]	Module-level documentation text, if available.	None

Functions

add_object

add_object(obj: DocObject) -> None

Add a documented object to the module.

Parameters:

Name	Type	Description	Default
obj	DocObject	Documentation object to register as a top-level member of the module.	required

get_all_objects

get_all_objects() -> Iterable[DocObject]

Return all top-level documentation objects in the module.

Returns:

Type	Description
Iterable[DocObject]	Iterable[DocObject]: An iterable of DocObject instances representing the module's public members.

get_object

get_object(name: str) -> DocObject

Retrieve a documented object by name.

Parameters:

Name	Type	Description	Default
name	str	Name of the object to retrieve.	required

Returns:

Name	Type	Description
DocObject	DocObject	The corresponding DocObject instance.

Raises:

Type	Description
KeyError	If no object with the given name exists.

Project

Project(name: str)

Representation of a documentation project.

A Project serves as the root container for all modules discovered during introspection. Each module is stored by its dotted import path.

Attributes:

Name	Type	Description
name	str	Name of the project.
modules	Dict[str, Module]	Mapping of module paths to Module instances.

Initialize a Project instance.

Parameters:

Name	Type	Description	Default
name	str	Name used to identify the documentation project.	required

Functions

add_module

add_module(module: Module) -> None

Register a module in the project.

Parameters:

Name	Type	Description	Default
module	Module	Module instance to add to the project.	required

get_all_modules

get_all_modules() -> Iterable[Module]

Return all modules contained in the project.

Returns:

Type	Description
Iterable[Module]	Iterable[Module]: An iterable of Module instances.

get_module

get_module(path: str) -> Module

Retrieve a module by its dotted path.

Parameters:

Name	Type	Description	Default
path	str	Fully qualified dotted module path (for example pkg.module).	required

Returns:

Name	Type	Description
Module	Module	The corresponding Module instance.

Raises:

Type	Description
KeyError	If the module does not exist in the project.

get_module_list

get_module_list() -> list[str]

Return the list of module import paths.

Returns:

Type	Description
list[str]	list[str]: A list containing the dotted paths of all modules in the project.