Metadata-Version: 2.5
Name: libspec-diataxis
Version: 0.1.0
Summary: Diataxis documentation structure base classes for libspec features
Requires-Python: >=3.13
Requires-Dist: libspec>=10.5.2
Description-Content-Type: text/markdown

# libspec-diataxis

Diátaxis-shaped documentation base classes for [libspec](https://github.com/libspec/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

```bash
uv add libspec-diataxis
```

or

```bash
pip install libspec-diataxis
```

---

## Quick Start

```python
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:

|                          | Acquisition (study) | Application (work)  |
|--------------------------|---------------------|---------------------|
| **Action (practical)**   | Tutorial            | How-to Guide        |
| **Cognition (theory)**   | Explanation         | Reference           |

Each quadrant maps to a required method on `Diataxis`:

| Method        | Quadrant      | Purpose                                                   |
|---------------|---------------|-----------------------------------------------------------|
| `tutorial()`  | action×study  | Learning-oriented narrative; leads the learner by hand   |
| `how_to()`    | action×work   | Goal-oriented directions for the already-competent user  |
| `reference()` | cognition×work| Neutral, complete, authoritative description              |
| `explanation()`| cognition×study| Context, background, the reasoning behind decisions    |

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](https://diataxis.fr).
