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

chore(release): 0.0.7

Browse Source 
Squash-merge lib-standardisation: adopt repo standards across packaging,
tooling, docs, and CI.

- standardize pyproject.toml (canonical packaging, lint config, extras, GSDFC pydoclint)
- add py.typed marker, modernize type hints and Google-style docstrings
- nest generated docs under docs/lib and docs/mcp; add hand-written wiki
- adopt standard Type A PyPI CI pipeline (tag==version guard + quality gate)
- promote generated CHANGELOG.md; bump version to 0.0.7
This commit is contained in:
Vishesh 'ironeagle' Bangotra
2026-10-17 02:16:44 +05:30
parent 8253c25928
commit 06ffd2febd
149 changed files with 7132 additions and 4594 deletions
Download Patch File Download Diff File Expand all files Collapse all files

122
docforge/loaders/griffe_loader.py
View File

@@ -6,21 +6,32 @@ Utilities for loading and introspecting Python modules using Griffe.
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.
---
Notes:
- All analysis is static; analyzed modules are never executed.
- Private members (names starting with `_`) are skipped during conversion.
- Imported aliases that cannot be resolved (stdlib/third-party names) are
skipped; aliases that resolve within the documented project are kept.
---
"""
import logging
from pathlib import Path
from typing import List, Optional
from griffe import (
GriffeLoader as _GriffeLoader,
ModulesCollection,
LinesCollection,
Object,
AliasResolutionError,
LinesCollection,
ModulesCollection,
Object,
)
from griffe import (
GriffeLoader as _GriffeLoader,
)
from docforge.models import Module, Project, DocObject
from docforge.models import DocObject, Module, Project
logger = logging.getLogger(__name__)
@@ -28,7 +39,7 @@ logger = logging.getLogger(__name__)
def discover_module_paths(
module_name: str,
project_root: Path | None = None,
) -> List[str]:
) -> list[str]:
"""
Discover Python modules within a package directory.
@@ -45,12 +56,12 @@ def discover_module_paths(
module_name (str):
Top-level package name to discover modules from.
project_root (Path, optional):
project_root (Path | None):
Root directory used to resolve module paths. If not provided, the
current working directory is used.
Returns:
List[str]:
list[str]:
A sorted list of unique dotted module import paths.
Raises:
@@ -65,7 +76,7 @@ def discover_module_paths(
if not pkg_dir.exists():
raise FileNotFoundError(f"Package not found: {pkg_dir}")
module_paths: List[str] = []
module_paths: list[str] = []
for path in pkg_dir.rglob("*.py"):
if path.name == "__init__.py":
@@ -87,6 +98,10 @@ class GriffeLoader:
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.
Attributes:
_loader (_GriffeLoader):
Internal Griffe loader with dedicated module and line collections.
"""
def __init__(self) -> None:
@@ -102,10 +117,10 @@ class GriffeLoader:
)
def load_project(
self,
module_paths: List[str],
project_name: Optional[str] = None,
skip_import_errors: bool = None,
self,
module_paths: list[str],
project_name: str | None = None,
skip_import_errors: bool | None = None,
) -> Project:
"""
Load multiple modules and assemble them into a Project model.
@@ -115,14 +130,14 @@ class GriffeLoader:
object.
Args:
module_paths (List[str]):
module_paths (list[str]):
List of dotted module import paths to load.
project_name (str, optional):
project_name (str | None):
Optional override for the project name. Defaults to the top-level
name of the first module.
skip_import_errors (bool, optional):
skip_import_errors (bool | None):
If True, modules that fail to load will be skipped instead of raising an error.
Returns:
@@ -171,6 +186,21 @@ class GriffeLoader:
Returns:
Module:
A populated `Module` instance.
Raises:
ImportError:
If the module cannot be loaded by Griffe.
KeyError:
If the loaded module is missing from the module collection.
Example:
Load a single module:
```python
loader = GriffeLoader()
module = loader.load_module("mypackage.submodule")
```
"""
self._loader.load(path)
griffe_module = self._loader.modules_collection[path]
@@ -204,6 +234,8 @@ class GriffeLoader:
for name, member in obj.members.items():
if name.startswith("_"):
continue
if not self._is_resolvable_alias(member):
continue
module.add_object(self._convert_object(member))
@@ -240,6 +272,8 @@ class GriffeLoader:
for name, member in obj.members.items():
if name.startswith("_"):
continue
if not self._is_resolvable_alias(member):
continue
doc_obj.add_member(self._convert_object(member))
except AliasResolutionError:
pass
@@ -250,7 +284,7 @@ class GriffeLoader:
# Safe extractors
# -------------------------
def _safe_docstring(self, obj: Object) -> Optional[str]:
def _safe_docstring(self, obj: Object) -> str | None:
"""
Safely extract a docstring from a Griffe object.
@@ -259,7 +293,7 @@ class GriffeLoader:
Griffe object to inspect.
Returns:
Optional[str]:
str | None:
The raw docstring text if available, otherwise `None`.
"""
try:
@@ -267,21 +301,57 @@ class GriffeLoader:
except AliasResolutionError:
return None
def _safe_signature(self, obj: Object) -> Optional[str]:
def _safe_signature(self, obj: Object) -> str | None:
"""
Safely extract the signature of a Griffe object.
Griffe exposes signatures as callables (``Object.signature``); the
method is invoked and stringified to produce a clean, stable signature.
Aliases that point outside the loaded project fail resolution and are
reported as `None`.
Args:
obj (Object):
Griffe object to inspect.
Returns:
Optional[str]:
String representation of the object's signature if available, otherwise `None`.
str | None:
Clean string representation of the object's signature if
available, otherwise `None`.
"""
try:
if hasattr(obj, "signature") and obj.signature:
return str(obj.signature)
except AliasResolutionError:
signature = getattr(obj, "signature", None)
if signature is None:
return None
if callable(signature):
signature = signature()
if not signature:
return None
return str(signature).strip() or None
except Exception:
return None
return None
def _is_resolvable_alias(self, obj: Object) -> bool:
"""
Report whether an object is a resolvable part of the documented API.
Aliases that cannot be resolved (stdlib or third-party imports) are
treated as noise and excluded from the model. Non-alias objects are
always resolvable.
Args:
obj (Object):
Griffe object to test.
Returns:
bool:
True if the object should be kept, False if it is an
unresolvable alias.
"""
if obj.kind.value != "alias":
return True
try:
_ = obj.canonical_path
except AliasResolutionError:
return False
return True

14
docforge/loaders/griffe_loader.pyi
View File

@@ -1,29 +1,25 @@
from typing import List, Optional
from pathlib import Path
from docforge.models import Module, Project
def discover_module_paths(
module_name: str,
project_root: Path | None = None,
) -> List[str]:
...
) -> list[str]: ...
class GriffeLoader:
"""Griffe-based introspection loaders.
This is the only supported introspection backend in doc-forge.
Converts Griffe results into `Project`, `Module`, and `DocObject` models.
"""
def __init__(self) -> None: ...
def load_project(
self,
module_paths: List[str],
project_name: Optional[str] = ...,
skip_import_errors: bool = ...,
module_paths: list[str],
project_name: str | None = ...,
skip_import_errors: bool | None = ...,
) -> Project:
"""Load a documentation project from Python modules."""