rlsbl.targets.docs.extract

Python source extraction -- docstrings and signatures via stdlib ast.

Functions

extract_python_docs

def extract_python_docs(paths, base_dir='.', exclude=None)

Extract documentation from Python source files.

Walks each path (relative to base_dir), finds .py files, parses with ast, and extracts module/class/function docstrings preserving hierarchy.

Args: paths: List of directory paths to scan (relative to base_dir). base_dir: Root directory for resolving relative paths. exclude: Optional list of path prefixes to skip (e.g. ["tests/", "templates/"]). Matched against the path relative to base_dir.

Returns: List of page dicts, one per module: [ { "module": "rlsbl.commands.release", "path": "rlsbl/commands/release.py", "docstring": "Release command...", "classes": [ {"name": "...", "docstring": "...", "methods": [...]} ], "functions": [ {"name": "run_cmd", "docstring": "...", "signature": "..."} ] } ]

Items without docstrings are skipped. Private members (names starting with '_') are included only if they have a docstring. Modules that end up with no documented functions or classes are omitted entirely. Directories whose name starts with '_' (other than __init__.py files) are pruned from the walk.

_has_documented_items

def _has_documented_items(page)

Return True if a page has at least one documented function or class.

A module that only has a module-level docstring but no documented functions or classes is not worth generating a standalone page for.

_extract_file

def _extract_file(filepath, base_dir)

Extract documentation from a single Python file.

Returns a page dict, or None if the file has no documentable content.

_extract_class

def _extract_class(node)

Extract class info including its methods.

Skips private classes unless they have a docstring.

_extract_function

def _extract_function(node)

Extract function/method info.

Skips private functions unless they have a docstring.

_build_signature

def _build_signature(node)

Build a human-readable function signature from ast.arguments.

Produces something like: (self, x, y=None, args, *kwargs)

_annotation_str

def _annotation_str(node)

Convert an annotation AST node to a string, or empty string if None.

_literal_repr

def _literal_repr(node)

Convert a default-value AST node to a readable string.

_path_to_module

def _path_to_module(rel_path)

Convert a relative file path to a dotted module name.

'rlsbl/commands/release.py' -> 'rlsbl.commands.release' 'rlsbl/__init__.py' -> 'rlsbl'