libspec-diataxis

Diátaxis-shaped documentation base classes for libspec feature hierarchies.

Inherit Diataxis into any libspec.Feature subclass and every feature in your project is required to articulate itself across all four Diátaxis quadrants — Tutorial, How-to Guide, Reference, and Explanation — before a spec can be generated.

Installation

uv add libspec-diataxis

or

pip install libspec-diataxis

Quick Start

from libspec.diataxis import Diataxis

# Your project's domain base class
class UIFeature(Diataxis): ...

# A fully-documented feature
class AwesomeNavBar(UIFeature):

    def date(self):
        return "2026-08-11"

    def description(self):
        return "Accessible, animated navigation bar with keyboard support."

    def tutorial(self):
        return (
            "In this tutorial we will build a minimal nav bar from scratch. "
            "We will add three links, watch the highlight move between them, "
            "and verify that the keyboard shortcut activates each item."
        )

    def how_to(self):
        return (
            "To highlight the active route, pass `active_index=<int>` to "
            "AwesomeNavBar().  To add keyboard support, ensure the parent "
            "element has `tabindex=0` and attach the provided `on_keydown` handler."
        )

    def reference(self):
        return (
            "AwesomeNavBar(items: list[str], active_index: int = 0,\n"
            "              on_change: Callable[[int], None] | None = None)\n"
            "  items         — ordered list of label strings\n"
            "  active_index  — zero-based index of the selected item\n"
            "  on_change     — optional callback invoked on selection change"
        )

    def explanation(self):
        return (
            "The nav bar uses a slot-based model so items remain decoupled from "
            "routing logic.  Active state is passed in, making the component "
            "purely presentational and trivially testable."
        )

The Four Quadrants

Diátaxis (diataxis.fr) organises documentation around two orthogonal dimensions of craft — action ↔ cognition × acquisition ↔ application — yielding four necessary and sufficient quadrants:

Each quadrant maps to a required method on Diataxis:

All four methods are mandatory. Omitting any one raises libspec.UnimplementedMethodError at spec-generation time.

How It Works

Diataxis subclasses libspec.Feature, which subclasses libspec.Ctx. The Ctx machinery collects zero-argument methods as template variables and injects them into the class docstring (a Jinja2 template). libspec.Spec then renders and serialises the result to XML or Component dataclasses.

The class docstring template:

Feature Specification: {{feature_name}}

{{description}}

## Tutorial
{{tutorial}}

## How-to Guide
{{how_to}}

## Reference
{{reference}}

## Explanation
{{explanation}}

Namespace Extension

libspec-diataxis ships a .pth + startup hook that appends src/libspec/ to libspec.__path__ at interpreter startup, enabling from libspec.diataxis import Diataxis even though libspec is a regular (non-namespace) package. No modifications to libspec are required.

License

Apache 2.0. See LICENSE.

Diátaxis is the work of Daniele Procida. See diataxis.fr.