[Agentic DX] django-docutils: low-to-high lift API and extension roadmap

[tony]

Context

Review focused on src/django_docutils/lib/{directives,roles,metadata}, templatetags, and docs.

Goal

Make extension points and stable API boundaries obvious for both humans and code agents.

Low-lift ideas

• Document supported public modules vs internal modules.
• Add a concise error taxonomy for rendering/metadata failures.
• Add task-oriented API examples (render, parse metadata, template usage).

Medium-lift ideas

• Add a stable facade module (for example django_docutils.api) for common operations.
• Standardize plugin registration docs for directives and roles.
• Add contract tests for documented entry points.

High-lift ideas

• Publish a machine-readable catalog of directives/roles and config knobs.
• Add compatibility metadata to docs for extension authors.

Done when

• Public surface is explicit.
• Extension points are codified and tested.
• Tooling can discover capabilities without source-diving.