Skip to content

# 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

    1

    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

    1

    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

    1

    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

    1

    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

    1

    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

    1

    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

    1

    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

    1

    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

    1

    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

    1

    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

    1

    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

    1

    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

    1

    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.