Models

docforge.models

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).

DocObject

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

Represents a documented Python object (class, function, method, etc.).

Attributes:

Name	Type	Description
name	str	Local name of the object.
kind	str	Type of object (e.g., 'class', 'function', 'attribute').
path	str	Full dotted import path to the object.
signature	Optional[str]	Callable signature, if applicable.
docstring	Optional[str]	Raw docstring content extracted from the source.
members	Dict[str, DocObject]	Dictionary mapping member names to their DocObject representations.

Initialize a new DocObject.

Parameters:

Name	Type	Description	Default
name	str	The local name of the object.	required
kind	str	The kind of object (e.g., 'class', 'function').	required
path	str	The full dotted path to the object.	required
signature	Optional[str]	The object's signature (for callable objects).	None
docstring	Optional[str]	The object's docstring, if any.	None

add_member

add_member(obj: DocObject) -> None

Add a child member to this object (e.g., a method to a class).

Parameters:

Name	Type	Description	Default
obj	DocObject	The child DocObject to add.	required

get_all_members

get_all_members() -> Iterable[DocObject]

Get all members of this object.

Returns:

Type	Description
Iterable[DocObject]	An iterable of child DocObject instances.

get_member

get_member(name: str) -> DocObject

Retrieve a child member by name.

Parameters:

Name	Type	Description	Default
name	str	The name of the member.	required

Returns:

Type	Description
DocObject	The requested DocObject.

Module

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

Represents a documented Python module or package.

Attributes:

Name	Type	Description
path	str	Dotted import path of the module.
docstring	Optional[str]	Module-level docstring content.
members	Dict[str, DocObject]	Dictionary mapping object names to their DocObject representations.

Initialize a new Module.

Parameters:

Name	Type	Description	Default
path	str	The dotted path of the module.	required
docstring	Optional[str]	The module's docstring, if any.	None

add_object

add_object(obj: DocObject) -> None

Add a documented object to the module.

Parameters:

Name	Type	Description	Default
obj	DocObject	The object to add.	required

get_all_objects

get_all_objects() -> Iterable[DocObject]

Get all top-level objects in the module.

Returns:

Type	Description
Iterable[DocObject]	An iterable of DocObject instances.

get_object

get_object(name: str) -> DocObject

Retrieve a member object by name.

Parameters:

Name	Type	Description	Default
name	str	The name of the object.	required

Returns:

Type	Description
DocObject	The requested DocObject.

Project

Project(name: str)

Represents a documentation project, serving as a container for modules.

Attributes:

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

Initialize a new Project.

Parameters:

Name	Type	Description	Default
name	str	The name of the project.	required

add_module

add_module(module: Module) -> None

Add a module to the project.

Parameters:

Name	Type	Description	Default
module	Module	The module to add.	required

get_all_modules

get_all_modules() -> Iterable[Module]

Get all modules in the project.

Returns:

Type	Description
Iterable[Module]	An iterable of Module objects.

get_module

get_module(path: str) -> Module

Retrieve a module by its dotted path.

Parameters:

Name	Type	Description	Default
path	str	The dotted path of the module (e.g., 'pkg.mod').	required

Returns:

Type	Description
Module	The requested Module.

get_module_list

get_module_list() -> list[str]

Get the list of all module dotted paths.

Returns:

Type	Description
list[str]	A list of module paths.