Writing docs

The docs site is MkDocs with Material and mkdocstrings.

Preview locally

ocx run -- task docs:serve

Browse to 127.0.0.1:8000. Pages live-reload on file changes.

Strict build (CI parity)

ocx run -- task docs:build

--strict flips any broken cross-reference, missing nav entry, or undefined symbol into a build failure. CI runs the same command.

Adding a page

1. Create the Markdown file under docs/.
2. Wire it into nav: in mkdocs.yml.
3. task docs:build to confirm --strict is happy.

Auto-API pages (mkdocstrings)

To render a class or function:

::: ocx_mirror_sdk.module.Symbol

mkdocstrings reads the live docstring. Update the docstring in src/, rebuild — done.

Embedding example scripts

PEP 723 example scripts under examples/ are embedded via pymdownx.snippets:

```python title="examples/01_shellcheck_rest.py"
#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.13"
# dependencies = [
#   "ocx-mirror-sdk @ git+https://github.com/ocx-sh/ocx-mirror-sdk@v0.3.0",
# ]
# ///
"""Minimal generator: shellcheck releases via REST → url_index JSON.

Usage:
    uv run examples/01_shellcheck_rest.py > shellcheck.json
"""

from ocx_mirror_sdk import IndexBuilder, list_releases


def main() -> None:
    releases = list_releases("koalaman", "shellcheck")

    builder = IndexBuilder()
    for r in releases:
        if r.prerelease or r.draft:
            continue
        builder.add_version(
            r.tag_name.lstrip("v"),
            assets={a.name: a.browser_download_url for a in r.assets},
        )

    builder.emit()


if __name__ == "__main__":
    main()

```

The snippet base paths are configured in mkdocs.yml. Snippets run unmodified — keep the source as the source of truth.