Requirements Library: Documentation infrastructure and examples

[akihikokuroda]

Set up overall documentation infrastructure for consistent docs across all sub-tasks.

Setup

• Ensure docs/docs/ pages follow Mellea conventions (no H1, no .md extensions, frontmatter required)
• Verify cross-references use correct link format
• Review generated API reference pages for completeness
• Create docs/examples/requirements/ directory structure
• Run markdownlint on all new/modified doc pages
• Create quick-start guides for common use cases

Part of #1023

[akihikokuroda]

Design: Documentation Infrastructure and Examples (Task #1127)

Overview

Task #1127 covers cross-cutting documentation work ensuring all Python requirements documentation is discoverable, well-organized, and integrated into the Mellea documentation site. This work goes beyond the failure matrix (#1124) to include:

1. Examples discovery — Ensure docs/examples/requirements/ is discoverable
2. Navigation integration — Add requirements docs to docs.json
3. API reference completeness — Verify all requirement classes have full docs
4. Quick-start guides — Document common usage patterns
5. Examples catalogue — Update docs/docs/examples/index.md

Additional Contents Beyond Task #1124

Task #1124 delivers the Failure Matrix: docs/docs/guides/python-requirements.md (300–600 lines, reference documentation mapping failures to requirements).

Task #1127 delivers infrastructure around that, including:

1. API Reference Pages

Status: Likely auto-generated from docstrings via audit_coverage.py

Deliverables:

• Review existing API docs for:
  • mellea/stdlib/requirements/python_tools.py classes/functions
  • mellea/stdlib/requirements/plotting/matplotlib.py classes/functions
  • Factory functions: python_tool_requirements(), python_plotting_requirements()
• Ensure all have complete Google-style docstrings
• Verify Raises: sections match all raised exceptions (CI gate)
• Link from guide pages to API reference

Files checked:

docs/docs/api/mellea/stdlib/requirements/
  ├── python-tools.md (auto-generated from python_tools.py docstrings)
  └── matplotlib.md (auto-generated from plotting/matplotlib.py docstrings)

2. Examples in docs/examples/requirements/

Status: Directory exists but needs content

Deliverables:

Create three example files:

a) python_tool_preset.py

# pytest: e2e, qualitative, granite_4_1
"""Using python_tool_sampling preset for safe Python code generation."""

# Shows:
# - Creating python_tool_sampling() preset
# - Passing to m.instruct()
# - Success/failure flows
# - Repair iteration reporting

b) python_plotting_preset.py (based on python_plotting_repair.py from PR #1040)

# pytest: e2e, qualitative, granite_4_1
"""Using python_plotting_sampling preset for matplotlib plotting code generation."""

# Shows:
# - Creating python_plotting_sampling() preset with output_path
# - Tool invocation with MelleaTool.from_callable()
# - Success/failure with file validation
# - Repair iteration reporting

c) custom_requirements.py

# pytest: unit, qualitative
"""Composing custom requirement lists for specific use cases."""

# Shows:
# - Mixing python_tool + matplotlib requirements
# - Optional requirements (ImportRestrictions only if needed)
# - Custom timeouts/output limits
# - Using with Sampling directly

Files to create:

docs/examples/requirements/
├── README.md (update)
├── python_tool_preset.py (NEW)
├── python_plotting_preset.py (NEW)
└── custom_requirements.py (NEW)

3. Examples Catalogue Update

File: docs/docs/examples/index.md

Current state: Lists all example categories, but "requirements" is not listed.

Change needed:

### Safety and validation

| Category | What it shows |
| -------- | ------------- |
| `requirements/` | Python tool requirements presets, failure modes, repair feedback, custom requirement composition |
| `safety/` | GuardianCheck for harm, jailbreak, profanity, social bias, violence, and groundedness |

4. Quick-Start Guide Page (Optional)

File: docs/docs/guides/python-requirements-quickstart.md (optional, can defer)

Purpose: Help new users quickly understand "when to use which preset"

Would cover:

• When to use python_tool_requirements() alone
• When to use python_plotting_requirements()
• Common customizations (import allowlists, output limits, timeouts)
• Common failures and how requirements prevent them

Decision: Include only if overall doc length demands splitting. If main failure matrix stays ≤600 lines, can defer this.

5. Navigation Integration

File: docs/docs/docs.json

Change needed: Add requirements pages to "How-To" section (or create new "Requirements" section)

Current "How-To" structure:

{
  "group": "How-To",
  "pages": [
    "how-to/generative-functions",
    "how-to/tools-and-agents",
    ...
  ]
}

Revised "How-To" structure (add):

{
  "group": "How-To",
  "pages": [
    "how-to/generative-functions",
    "how-to/tools-and-agents",
    "how-to/python-requirements",  // NEW guide page (optional quick-start)
    "how-to/handling-exceptions",
    ...
  ]
}

Alternative: Add to existing "Reference" or "Concepts" section if better fit

6. API Reference Links

From: docs/docs/api/mellea/stdlib/requirements/ (auto-generated)

To ensure:

• Classes have full Google-style docstrings with:
  • One-line summary
  • Detailed description
  • Args: section
  • Returns: section (if applicable)
  • Raises: section with all exceptions
• Factory functions documented:
  • python_tool_requirements() function
  • python_plotting_requirements() function

7. Glossary Updates (If Needed)

File: docs/docs/reference/glossary.md

Check:

• Do entries exist for:
  • Requirement / req() / check()
  • ValidationResult
  • Sampling strategy
• If missing, add concise entries with examples

Task Checklist

Examples

• Create docs/examples/requirements/python_tool_preset.py with pytest markers
• Create docs/examples/requirements/python_plotting_preset.py (based on PR feat: python tools requirement #1040)
• Create docs/examples/requirements/custom_requirements.py
• Update docs/examples/requirements/README.md with new examples
• Verify all examples have proper docstrings and pytest markers
• Run examples to verify they work: uv run docs/examples/requirements/*.py

Documentation Integration

• Update docs/docs/examples/index.md to include "requirements" category
• Add requirements pages to docs/docs/docs.json navigation
• Verify API reference pages exist and link correctly
• Add any missing glossary entries

Quality Gates

• All example code blocks verified against current Mellea source
• All links in docs (internal and external) resolve correctly
• markdownlint passes on all new/modified doc pages
• Examples run successfully with CI markers
• No broken cross-references (guide ↔ API reference ↔ examples)

Files to Modify/Create

Create:

docs/examples/requirements/python_tool_preset.py
docs/examples/requirements/python_plotting_preset.py
docs/examples/requirements/custom_requirements.py
docs/docs/guides/python-requirements.md (from task #1124)

Modify:

docs/examples/requirements/README.md
docs/docs/examples/index.md
docs/docs/docs.json
docs/docs/reference/glossary.md (if needed)

Success Criteria

✅ Examples in docs/examples/requirements/ are discoverable via docs.json
✅ Examples catalogue lists requirements examples
✅ Navigation includes link to requirements documentation
✅ API references have complete docstrings (passes audit_coverage.py)
✅ All internal links resolve (no broken refs)
✅ All examples are marked with pytest headers and run successfully
✅ Glossary has all necessary terms
✅ markdownlint passes on all docs pages

Integration Points

1. From guide pages → Link to API reference for specifics
2. From API reference → Link to guide for usage patterns
3. From examples → Link to guide for understanding failures
4. From examples catalogue → Discovery of requirements examples
5. From navigation → Access to main requirements guide

Minimal vs Complete Approach

Minimal (get it done):

• ✅ Create 2-3 example files
• ✅ Update examples catalogue
• ✅ Update docs.json navigation
• ✅ Verify links resolve

Complete (high polish):

• ✅ All of above plus:
• ✅ Create optional quick-start guide page
• ✅ Add comprehensive API docs
• ✅ Glossary entries for any missing terms
• ✅ Cross-link strategy fully implemented

Recommend: Minimal + examples, defer quick-start to post-merge based on feedback.