agilab-docs
Documentation workflow for AGILAB (sources vs generated HTML, public constraints, consistency checks).
When & Why to Use This Skill
This Claude skill optimizes the AGILAB documentation workflow by managing the lifecycle of technical docs from source files to generated HTML. It ensures high-quality output through automated Sphinx build triggers, strict consistency checks for terminology and diagrams, and a robust privacy filter that prevents the accidental disclosure of non-public internal repositories or application modules.
Use Cases
- Automating Sphinx Documentation Builds: Streamline the process of generating HTML from source files using specific toolchains like uv and Python, ensuring that manual edits are never made to generated files.
- Enforcing Privacy Constraints: Automatically scan and sanitize public-facing documentation to ensure no private app names or internal repository structures are mentioned, maintaining organizational security.
- Maintaining Structural Consistency: Standardize technical terminology (e.g., 'Page bundles', 'Apps-pages') and ensure that SVG diagrams and mathematical equations remain aligned with the surrounding text.
- Documentation Quality Assurance: Perform consistency checklists during the editing process to remove stale labels, update headings, and verify that all math blocks render correctly via Sphinx extensions.
| name | agilab-docs |
|---|---|
| description | Documentation workflow for AGILAB (sources vs generated HTML, public constraints, consistency checks). |
| license | BSD-3-Clause (see repo LICENSE) |
| updated | 2026-01-09 |
Docs Skill (AGILAB)
Use this skill when editing docs/source or any docs build tooling.
Source Of Truth
docs/htmlis generated: do not hand-edit it.- Edit
docs/source/*and regenerate.
Public Docs Constraint
- Public documentation must not mention non-public apps/repositories.
- Keep examples generic and refer to “external apps repository” rather than naming private app modules.
Build / Validate
- Local Sphinx build (repo root):
uv --preview-features extra-build-dependencies run python -m sphinx -b html docs/source docs/html
Consistency Checklist
- Use consistent naming: “Pages”, “Page bundles”, “Apps-pages” (avoid near-duplicate headings).
- Keep diagrams (SVG) aligned with wording; remove stale labels when sections are removed.
- Ensure math renders via Sphinx math extension; keep equations in
.. math::blocks when needed.