Models

docforge.models

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]`	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:

Type	Description
`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]`	An iterable of `DocObject` instances representing the
`Iterable[DocObject]`	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:

Type	Description
`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]`	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:

Type	Description
`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]`	A list containing the dotted paths of all modules in the project.