Skip to content

Generate an API reference with mkdocstrings #137

Open

Description

@chiruu12

We have fourteen hand-written guides and no generated API reference. Every comparable project has one (llm-guard, guardrails, NeMo-Guardrails), and it is the page people search for when they want to know what a method actually takes.

The good news is the groundwork is already done. 39 of the 40 names in unplug.__all__ have docstrings. They are one-line summaries rather than full Args/Returns blocks, but combined with the type annotations that is enough to render a genuinely useful reference. No docstring rewrite is needed first.

get_correlation_id is the one name with no docstring.

What to do:

  1. Add mkdocstrings[python] to docs-requirements.txt and the plugin to mkdocs.yml.
  2. Add a docs/reference/ section with a page per major type: Guard, ScanResult, Finding, GuardConfig, and the enums.
  3. Add a Reference nav section.

Do not use unplug.core.* paths in the reference. docs/PUBLIC_API.md defines what is public, and the reference should cover that surface and nothing below it.

Acceptance:

  • Every name in unplug.__all__ is reachable from the reference nav.
  • mkdocs build --strict passes.
  • Signatures render with types, and the summary line appears under each.

Not a first issue.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions