Metadata-Version: 2.4
Name: douki
Version: 0.10.2
Summary: Documetatio from annotations
License: BSD 3 Clause
License-File: LICENSE
Author: Ivan Ogasawara
Author-email: ivan.ogasawara@gmail.com
Requires-Python: >=3.10,<4
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: jsonschema (>=4)
Requires-Dist: pyyaml (>=6)
Requires-Dist: rich (>=13)
Requires-Dist: tomli (>=2.0.0) ; python_version < "3.11"
Requires-Dist: typer (>=0.9)
Description-Content-Type: text/markdown

# Douki

**Language-agnostic YAML docstrings for Python.**

Douki is a developer tool that uses a structured YAML format inside Python
docstrings. It keeps your docstrings in sync with your function signatures and
validates them against a schema — all without adding a runtime dependency to
your package.

## Why Douki?

- **Structured** — docstrings are YAML, not free-form text. Parameters have
  `type`, `description`, `optional`, and `default` fields.
- **Auto-synced** — `douki sync` adds new parameters, removes stale ones, and
  updates return types automatically.
- **Validated** — every docstring is checked against a JSON Schema so typos and
  invalid fields are caught early.
- **Dev-only** — Douki is a development tool. It does **not** need to be a
  runtime dependency of your package.
- **Migratable** — convert existing NumPy-style docstrings with
  `douki migrate numpydoc`.

## Quick Start

Install Douki as a dev dependency:

```bash
pip install douki
```

Write a docstring in Douki YAML format:

```python
def add(a: int, b: int = 0) -> int:
    """
    title: Add two integers
    parameters:
      a:
        type: int
        description: First value.
      b:
        type: int
        description: Second value.
        default: 0
    returns:
      type: int
      description: Sum of a and b.
    """
    return a + b
```

Sync your docstrings with the actual signatures:

```bash
# Preview changes
douki check src/

# Apply changes in-place
douki sync src/
```

## What's Next?

- [Installation](installation.md) — install via pip, conda, or from source
- [Usage Guide](usage.md) — CLI commands, YAML schema, and migration
- [Changelog](changelog.md) — release history
- [Contributing](contributing.md) — how to contribute

