aetos/doc-forge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

updated docs strings and added README.md

Browse Source
This commit is contained in:
Vishesh 'ironeagle' Bangotra
2026-03-08 17:59:55 +05:30
parent e8e16f3996
commit 8253c25928
37 changed files with 1091 additions and 834 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
docforge/loaders/__init__.py
View File

@@ -1,13 +1,14 @@
"""
# Summary
Loader layer for doc-forge.
The ``docforge.loaders`` package is responsible for discovering Python modules
The `docforge.loaders` package is responsible for discovering Python modules
and extracting documentation data using static analysis.
---
Overview
--------
# Overview
This layer converts Python source code into an intermediate documentation
model used by doc-forge. It performs module discovery, introspection, and
@@ -17,9 +18,9 @@ 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.
hierarchies using the `griffe` library without executing the code.
- **Public API filtering** – Exclude private members (names prefixed with
``_``) to produce clean public documentation structures.
`_`) to produce clean public documentation structures.
---
"""

93
docforge/loaders/griffe_loader.py
View File

@@ -1,7 +1,9 @@
"""
# Summary
Utilities for loading and introspecting Python modules using Griffe.
This module provides the ``GriffeLoader`` class and helper utilities used to
This module provides the `GriffeLoader` class and helper utilities used to
discover Python modules, introspect their structure, and convert the results
into doc-forge documentation models.
"""
@@ -30,25 +32,30 @@ def discover_module_paths(
"""
Discover Python modules within a package directory.
The function scans the filesystem for ``.py`` files inside the specified
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.
- Directories containing `__init__.py` are treated as packages.
- Each `.py` file is treated as a module.
- Results are returned as dotted import paths.
Args:
module_name: Top-level package name to discover modules from.
project_root: Root directory used to resolve module paths. If not
provided, the current working directory is used.
module_name (str):
Top-level package name to discover modules from.
project_root (Path, optional):
Root directory used to resolve module paths. If not provided, the
current working directory is used.
Returns:
A sorted list of unique dotted module import paths.
List[str]:
A sorted list of unique dotted module import paths.
Raises:
FileNotFoundError: If the specified package directory does not exist.
FileNotFoundError:
If the specified package directory does not exist.
"""
if project_root is None:
@@ -78,8 +85,8 @@ class 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.
code and transform the extracted information into `Project`, `Module`,
and `DocObject` instances used by doc-forge.
"""
def __init__(self) -> None:
@@ -103,24 +110,31 @@ class GriffeLoader:
"""
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``
Each module path is introspected and converted into a `Module`
instance. All modules are then aggregated into a single `Project`
object.
Args:
module_paths: List of dotted module import paths to load.
project_name: Optional override for the project name. Defaults
to the top-level name of the first module.
skip_import_errors: If True, modules that fail to load will be
skipped instead of raising an error.
module_paths (List[str]):
List of dotted module import paths to load.
project_name (str, optional):
Optional override for the project name. Defaults to the top-level
name of the first module.
skip_import_errors (bool, optional):
If True, modules that fail to load will be skipped instead of raising an error.
Returns:
A populated ``Project`` instance containing the loaded modules.
Project:
A populated `Project` instance containing the loaded modules.
Raises:
ValueError: If no module paths are provided.
ImportError: If a module fails to load and
``skip_import_errors`` is False.
ValueError:
If no module paths are provided.
ImportError:
If a module fails to load and `skip_import_errors` is False.
"""
if not module_paths:
raise ValueError("At least one module path must be provided")
@@ -148,13 +162,15 @@ class GriffeLoader:
Load and convert a single Python module.
The module is introspected using Griffe and then transformed into
a doc-forge ``Module`` model.
a doc-forge `Module` model.
Args:
path: Dotted import path of the module.
path (str):
Dotted import path of the module.
Returns:
A populated ``Module`` instance.
Module:
A populated `Module` instance.
"""
self._loader.load(path)
griffe_module = self._loader.modules_collection[path]
@@ -170,13 +186,15 @@ class GriffeLoader:
Convert a Griffe module object into a doc-forge Module.
All public members of the module are recursively converted into
``DocObject`` instances.
`DocObject` instances.
Args:
obj: Griffe object representing the module.
obj (Object):
Griffe object representing the module.
Returns:
A populated ``Module`` model.
Module:
A populated `Module` model.
"""
module = Module(
path=obj.path,
@@ -200,10 +218,12 @@ class GriffeLoader:
recursively.
Args:
obj: Griffe object representing a documented Python object.
obj (Object):
Griffe object representing a documented Python object.
Returns:
A ``DocObject`` instance representing the converted object.
DocObject:
A `DocObject` instance representing the converted object.
"""
kind = obj.kind.value
signature = self._safe_signature(obj)
@@ -235,10 +255,12 @@ class GriffeLoader:
Safely extract a docstring from a Griffe object.
Args:
obj: Griffe object to inspect.
obj (Object):
Griffe object to inspect.
Returns:
The raw docstring text if available, otherwise ``None``.
Optional[str]:
The raw docstring text if available, otherwise `None`.
"""
try:
return obj.docstring.value if obj.docstring else None
@@ -250,11 +272,12 @@ class GriffeLoader:
Safely extract the signature of a Griffe object.
Args:
obj: Griffe object to inspect.
obj (Object):
Griffe object to inspect.
Returns:
String representation of the object's signature if available,
otherwise ``None``.
Optional[str]:
String representation of the object's signature if available, otherwise `None`.
"""
try:
if hasattr(obj, "signature") and obj.signature: