Loaders

docforge.loaders

Loader layer for doc-forge.

The docforge.loaders package is responsible for discovering Python modules and extracting documentation data using static analysis.

Overview

This layer converts Python source code into an intermediate documentation model used by doc-forge. It performs module discovery, introspection, and initial filtering before the data is passed to the core documentation models.

Core capabilities include:

Module discovery – Locate Python modules and packages within a project.
Static introspection – Parse docstrings, signatures, and object hierarchies using the griffe library without executing the code.
Public API filtering – Exclude private members (names prefixed with _) to produce clean public documentation structures.

Classes

GriffeLoader

1	`GriffeLoader()`

Load Python modules using Griffe and convert them into doc-forge models.

This loader uses the Griffe introspection engine to analyze Python source code and transform the extracted information into Project, Module, and DocObject instances used by doc-forge.

Initialize the Griffe-backed loader.

Creates an internal Griffe loader instance with dedicated collections for modules and source lines.

Functions

load_module

load_module(path: str) -> Module

Load and convert a single Python module.

The module is introspected using Griffe and then transformed into a doc-forge Module model.

Parameters:

Name	Type	Description	Default
`path`	`str`	Dotted import path of the module.	required

Returns:

Type	Description
`Module`	A populated `Module` instance.

load_project

load_project(module_paths: List[str], project_name: Optional[str] = None, skip_import_errors: bool = None) -> Project

Load multiple modules and assemble them into a Project model.

Each module path is introspected and converted into a Module instance. All modules are then aggregated into a single Project object.

Parameters:

Name	Type	Description	Default
`module_paths`	`List[str]`	List of dotted module import paths to load.	required
`project_name`	`Optional[str]`	Optional override for the project name. Defaults to the top-level name of the first module.	`None`
`skip_import_errors`	`bool`	If True, modules that fail to load will be skipped instead of raising an error.	`None`

Returns:

Type	Description
`Project`	A populated `Project` instance containing the loaded modules.

Raises:

Type	Description
`ValueError`	If no module paths are provided.
`ImportError`	If a module fails to load and `skip_import_errors` is False.

Functions

discover_module_paths

discover_module_paths(module_name: str, project_root: Path | None = None) -> List[str]

Discover Python modules within a package directory.

The function scans the filesystem for .py files inside the specified package and converts them into dotted module import paths.

Discovery rules:

Directories containing __init__.py are treated as packages.
Each .py file is treated as a module.
Results are returned as dotted import paths.

Parameters:

Name	Type	Description	Default
`module_name`	`str`	Top-level package name to discover modules from.	required
`project_root`	`Path \| None`	Root directory used to resolve module paths. If not provided, the current working directory is used.	`None`

Returns:

Type	Description
`List[str]`	A sorted list of unique dotted module import paths.

Raises:

Type	Description
`FileNotFoundError`	If the specified package directory does not exist.