Documentation¶

This page provides reference for how the documentation site is built. Including stub generation, API reference generation, and doc comment format.

Site Overview¶

The documentation site is built with MkDocs using the Material theme. Configuration lives in mkdocs.yml.

Plugin	Purpose
`mkdocs-gen-files`	Runs `docs/gen_ref_pages.py` to generate API reference pages
`mkdocstrings`	Renders docstrings from `python/kaspa/` stub files into HTML
`mike`	Handles documentation versioning

Stub Generation Pipeline¶

Type stub files (.pyi) serve two purposes:

IDE support - Autocompletion and type checking for the native module
API documentation - Source for auto-generated API Reference pages

Stub Generation¶

Stubs are generated automatically during ./build-dev and ./build-release, or manually:

cargo run --bin stub-gen

The generator (src/bin/stub_gen.rs) performs:

pyo3-stub-gen extracts types and signatures from Rust source
Post-processing fixes enum names (Py prefix removal), RPC method signatures
Appends RPC TypedDicts from kaspa_rpc.pyi (manually maintained)
Outputs python/kaspa/__init__.pyi and python/kaspa/exceptions/__init__.pyi

The SilverScript bindings have their own generator (crates/silverscript/src/bin/stub_gen.rs) writing python/kaspa/experimental/silverscript/__init__.pyi. CI regenerates that stub and fails if the committed copy differs, so two things are worth knowing:

pyo3-stub-gen embeds Rust doc comments in the stub, so editing a doc comment in crates/silverscript/ makes the stub stale. Re-run ./build-dev and commit the regenerated .pyi in the same change.
pyo3-stub-gen is a caret requirement. Cargo.lock pins it, so CI is deterministic, but a cargo update that bumps it can reformat every stub at once. Regenerate and review in a standalone commit if that happens.

API Reference Generation¶

At docs build time (mkdocs build or mkdocs serve):

docs/gen_ref_pages.py parses python/kaspa/__init__.pyi and python/kaspa/exceptions/__init__.pyi for classes, functions, enums, and exceptions
Groups objects by type (Class, Enum, Function, TypedDict)
Generates reference/*.md pages (one per class/function)
mkdocstrings renders final HTML from the docstrings

Building Docs¶

mkdocs serve              # Local preview at http://127.0.0.1:8000
mkdocs build --strict     # Production build to site/

Doc Comment Format¶

Required Attributes¶

Item Type	Required Attribute
Class	`#[gen_stub_pyclass]` before `#[pyclass]`
Methods	`#[gen_stub_pymethods]` before `#[pymethods]`
Function	`#[gen_stub_pyfunction]` before `#[pyfunction]`

Class/Struct Documentation¶

/// Brief description of the class.
///
/// Extended description with additional details.
#[gen_stub_pyclass]
#[pyclass(name = "ClassName")]
pub struct PyClassName(pub NativeType);

Method/Function Documentation¶

Uses Google-style docstrings for mkdocstrings:

/// Brief description of the method.
///
/// Args:
///     param_name: Description of the parameter.
///
/// Returns:
///     ReturnType: Description of return value.
///
/// Raises:
///     Exception: When the exception occurs.
#[new]
pub fn constructor(param_name: &str) -> PyResult<Self> {
    // ...
}

Docstring Sections¶

Section	Purpose
`Args:`	Parameter documentation
`Returns:`	Return value documentation
`Raises:`	Exception documentation
`Note:`	Additional information
`Example:`	Code examples