Implementation:Online ml River Docs Parse
| Knowledge Sources | |
|---|---|
| Domains | Documentation, API_Generation, Static_Analysis |
| Last Updated | 2026-02-08 16:00 GMT |
Overview
Automated API reference documentation generator that extracts docstrings and creates MkDocs-compatible markdown.
Description
Parses River's source code using Python's inspect module and numpydoc to extract docstrings, signatures, parameters, examples, and references. Generates structured markdown files for MkDocs with automatic cross-linking between API elements. Handles classes, functions, methods, and module hierarchies. Includes linkification that transforms text references (e.g., river.linear_model.LogisticRegression) into hyperlinks.
Usage
Use to regenerate River's API documentation when code changes. Run as a CLI tool during documentation builds to keep API reference synchronized with source code. Essential for maintaining accurate, up-to-date documentation.
Code Reference
Source Location
- Repository: Online_ml_River
- File: docs/parse/__main__.py
Signature
def print_docstring(obj, file):
"""Prints a class's or function's docstring to a file."""
...
def print_module(mod, path, overview, depth=0, verbose=False):
"""Processes a module and generates documentation files."""
...
def print_library(library: str, output_dir: pathlib.Path, verbose=False):
"""Generates complete API reference for a library."""
...
def linkify_docs(library: str, docs_dir: pathlib.Path, verbose=False):
"""Adds hyperlinks to API references in documentation."""
...
class Linkifier:
"""Converts text references to API elements into hyperlinks."""
def __init__(self, library):
...
def linkify(self, text, prefix):
...
Import
# Run as CLI tool
python -m docs.parse river --out docs --verbose
I/O Contract
| Function | Parameters | Description |
|---|---|---|
| print_library | library: str, output_dir: Path, verbose: bool | Generates full API reference |
| linkify_docs | library: str, docs_dir: Path, verbose: bool | Adds cross-reference links |
| print_docstring | obj, file | Extracts and formats docstring |
| print_module | mod, path, overview, depth, verbose | Processes module recursively |
Usage Examples
# Command line usage
# Generate API docs for River
# python -m docs.parse river --out docs --verbose
# This will:
# 1. Scan all modules in river.api
# 2. Extract docstrings from classes and functions
# 3. Generate markdown files in docs/api/
# 4. Create overview pages with links
# 5. Linkify cross-references in all docs
# Example of what it processes:
from river import linear_model
# Extracts this:
# - Class name: LogisticRegression
# - Parameters with types and defaults
# - Method signatures
# - Examples from docstrings
# - References section
# Programmatic usage
import pathlib
from docs.parse.__main__ import print_library, linkify_docs
# Generate API reference
print_library(
library='river',
output_dir=pathlib.Path('docs/api'),
verbose=True
)
# Add hyperlinks
linkify_docs(
library='river',
docs_dir=pathlib.Path('docs'),
verbose=True
)
# Key features:
# - Parses NumPy-style docstrings
# - Extracts type annotations from signatures
# - Handles method inheritance
# - Formats code examples with syntax highlighting
# - Creates navigable directory structure
# - Cross-links API references
# - Handles Cython classes
# - Preserves doctest examples
# Output structure:
# docs/api/
# overview.md
# linear-model/
# LogisticRegression.md
# LinearRegression.md
# ...
# preprocessing/
# StandardScaler.md
# ...