documentation-build

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.

Documentation Build Validation

Scope

Build validation only: detect documentation build configuration, run applicable build targets, collect all errors and warnings, and categorize by severity.

Inputs

• Repository root.

Actions

1. Identify documentation root: Detect docs roots in this order:

   • docs/
   • Repository root, when both conf.py and Makefile exist
   • 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.

2. Detect build configuration: Check for the presence of:

   • conf.py in the detected docs root
   • Makefile in the detected docs root
   • Optional: .readthedocs.yaml in the detected docs root or at repository root

   If Sphinx build artifacts are absent in the target repository, report "not applicable" in findings and exit cleanly.

3. Run build targets (when applicable):

   cd <docs_root>
   # Use clean-doc when available, otherwise fall back to clean
   if make -n clean-doc 2>/dev/null; 
     make clean-doc
   
     make clean
   
   make html