// Validates documentation builds successfully. Use when checking Sphinx/RTD build integrity or diagnosing build failures. Reports errors, warnings, and build configuration issues.
Enforces project documentation style guide compliance for tone, voice, terminology, punctuation, and formatting. Use when checking documentation style or validating MyST/reST syntax. Cites specific style guide violations.
Analyzes documentation against Diataxis framework (Tutorial, How-to, Reference, Explanation). Use when reviewing documentation structure or classifying content type. Identifies misalignments between declared category and actual content.
Performs comprehensive documentation review including build validation, Diataxis analysis, structure audit, accuracy verification, and style compliance. Use when reviewing documentation changes or auditing documentation quality.
Validates documentation structural integrity including heading hierarchy, metadata, file naming, navigation, and cross-references. Use when checking documentation organization or validating toctree structure.
Verifies documentation accuracy by cross-referencing claims, CLI commands, API signatures, and configuration against source code. Use when validating documentation correctness or checking code-docs consistency. Flags unsupported or outdated claims.
| name | documentation-build |
| description | Validates documentation builds successfully. Use when checking Sphinx/RTD build integrity or diagnosing build failures. Reports errors, warnings, and build configuration issues. |
Build validation only: detect documentation build configuration, run applicable build targets, collect all errors and warnings, and categorise by severity.
Identify documentation directory: The docs/ directory
is the default location for Sphinx documentation.
If not found, search common doc roots in this order:
doc/, documentation/, site/, docs-src/.
If still not found, perform a bounded search for conf.py
(max depth 4) and use its parent as the docs root.
Detect build configuration: Check for the presence of:
.readthedocs.yamldocs/conf.pydocs/ directoryIf RTD artefacts are absent in the target repository, report "not applicable" in findings and exit cleanly.
Run build targets (when applicable):
cd docs
make clean
make html
Run additional checks for targets that exist. Check each target before running to avoid false failures:
# Check and run each target if available
for target in spelling linkcheck woke lint-md; do
if make -n $target 2>/dev/null; then
make $target
fi
done
Capture output and handle failures: If any command fails:
make clean to reset build stateWarnings must be collected and reported, but are not blocking unless the repository explicitly treats warnings as errors.
Categorise findings by severity:
Verify completion: Confirm the validation completed:
State the completion status:
✓ Build validation complete: [N] errors, [M] warnings found✓ Build validation complete: No issues found✓ Build validation: Not applicable - RTD artifacts not detectedA build validation report listing all errors and warnings, categorised by severity. If RTD artefacts are not detected, report "Not applicable -- RTD artefacts not detected in target repo".