Index

provide.testkit.quality.documentation

Documentation coverage analysis for provide-testkit.

Provides documentation coverage analysis using interrogate and other tools. Integrates with the quality framework for comprehensive docstring analysis.

Features: - Docstring coverage analysis with interrogate - Module, class, and function documentation checking - Integration with quality gates - Configurable exclusions and requirements

Usage

Basic documentation coverage

def test_with_docs(documentation_checker): result = documentation_checker.check(path) assert result.passed

Documentation with quality gates

runner = QualityRunner() results = runner.run_with_gates(path, {"documentation": 80.0})

Classes

DocumentationChecker

DocumentationChecker(config: dict[str, Any] | None = None)

Documentation coverage checker using interrogate.

Provides high-level interface for documentation analysis with automatic artifact management and integration with the quality framework.

Initialize documentation checker.

Parameters:

Name	Type	Description	Default
config	dict[str, Any] | None	Documentation checker configuration options	None

Source code in provide/testkit/quality/documentation/checker.py

def __init__(self, config: dict[str, Any] | None = None) -> None:
    """Initialize documentation checker.

    Args:
        config: Documentation checker configuration options
    """
    if not INTERROGATE_AVAILABLE:
        raise QualityToolError(
            "Interrogate not available. Install with: pip install interrogate", tool="documentation"
        )

    self.config = config or {}
    self.artifact_dir: Path | None = None

Functions

analyze

analyze(path: Path, **kwargs: Any) -> QualityResult

Run documentation analysis on the given path.

Parameters:

Name	Type	Description	Default
path	Path	Path to analyze	required
**kwargs	Any	Additional options including artifact_dir	{}

Returns:

Type	Description
QualityResult	QualityResult with documentation analysis data

Source code in provide/testkit/quality/documentation/checker.py

def analyze(self, path: Path, **kwargs: Any) -> QualityResult:
    """Run documentation analysis on the given path.

    Args:
        path: Path to analyze
        **kwargs: Additional options including artifact_dir

    Returns:
        QualityResult with documentation analysis data
    """
    self.artifact_dir = kwargs.get("artifact_dir", Path(".documentation"))
    start_time = time.time()

    try:
        # Run interrogate documentation analysis
        result = self._run_interrogate_analysis(path)
        result.execution_time = time.time() - start_time

        # Generate artifacts
        self._generate_artifacts(result)

        return result

    except Exception as e:
        return QualityResult(
            tool="documentation",
            passed=False,
            details={"error": str(e), "error_type": type(e).__name__},
            execution_time=time.time() - start_time,
        )

report

report(
    result: QualityResult, format: str = "terminal"
) -> str

Generate report from QualityResult (implements QualityTool protocol).

Parameters:

Name	Type	Description	Default
result	QualityResult	Documentation result	required
format	str	Report format	'terminal'

Returns:

Type	Description
str	Formatted report

Source code in provide/testkit/quality/documentation/checker.py

def report(self, result: QualityResult, format: str = "terminal") -> str:
    """Generate report from QualityResult (implements QualityTool protocol).

    Args:
        result: Documentation result
        format: Report format

    Returns:
        Formatted report
    """
    if format == "terminal":
        return self._generate_text_report(result)
    elif format == "json":
        return json.dumps(
            {
                "tool": result.tool,
                "passed": result.passed,
                "score": result.score,
                "details": result.details,
            },
            indent=2,
        )
    else:
        return str(result.details)

DocumentationFixture

DocumentationFixture(
    config: dict[str, Any] | None = None,
    artifact_dir: Path | None = None,
)

Bases: BaseQualityFixture

Pytest fixture for documentation coverage analysis.

Provides easy access to documentation coverage checking with automatic setup and teardown. Integrates with the quality framework fixtures.

Initialize documentation fixture.

Parameters:

Name	Type	Description	Default
config	dict[str, Any] | None	Documentation checker configuration	None
artifact_dir	Path | None	Directory for artifacts	None

Source code in provide/testkit/quality/documentation/fixture.py

def __init__(self, config: dict[str, Any] | None = None, artifact_dir: Path | None = None) -> None:
    """Initialize documentation fixture.

    Args:
        config: Documentation checker configuration
        artifact_dir: Directory for artifacts
    """
    super().__init__(config or {}, artifact_dir)
    self.analyzer: DocumentationChecker | None = None

Functions

analyze

analyze(path: Path) -> dict[str, Any]

Run documentation coverage analysis.

Parameters:

Name	Type	Description	Default
path	Path	Path to analyze	required

Returns:

Type	Description
dict[str, Any]	Analysis results as dict

Source code in provide/testkit/quality/documentation/fixture.py

def analyze(self, path: Path) -> dict[str, Any]:
    """Run documentation coverage analysis.

    Args:
        path: Path to analyze

    Returns:
        Analysis results as dict
    """
    if not self.analyzer:
        return {"error": "Analyzer not available"}

    result = self.analyzer.analyze(path, artifact_dir=self.artifact_dir)
    self.add_result(result)

    return {
        "passed": result.passed,
        "score": result.score,
        "grade": result.details.get("grade"),
        "total_coverage": result.details.get("total_coverage"),
        "covered_count": result.details.get("covered_count"),
        "missing_count": result.details.get("missing_count"),
        "total_count": result.details.get("total_count"),
        "file_coverage": result.details.get("file_coverage", []),
        "thresholds": result.details.get("thresholds", {}),
        "execution_time": result.execution_time,
    }

check

check(
    path: Path,
    min_coverage: float | None = None,
    min_grade: str | None = None,
    min_score: float | None = None,
) -> dict[str, Any]

Check documentation coverage with optional thresholds.

Parameters:

Name	Type	Description	Default
path	Path	Path to check	required
min_coverage	float | None	Minimum coverage percentage required	None
min_grade	str | None	Minimum grade required (A, B, C, D, F)	None
min_score	float | None	Minimum score required	None

Returns:

Type	Description
dict[str, Any]	Check results including pass/fail status

Source code in provide/testkit/quality/documentation/fixture.py

def check(
    self,
    path: Path,
    min_coverage: float | None = None,
    min_grade: str | None = None,
    min_score: float | None = None,
) -> dict[str, Any]:
    """Check documentation coverage with optional thresholds.

    Args:
        path: Path to check
        min_coverage: Minimum coverage percentage required
        min_grade: Minimum grade required (A, B, C, D, F)
        min_score: Minimum score required

    Returns:
        Check results including pass/fail status
    """
    if not self._setup_complete:
        self.setup()

    # Update config with provided thresholds
    if min_coverage is not None:
        self.config["min_coverage"] = min_coverage
    if min_grade is not None:
        self.config["min_grade"] = min_grade
    if min_score is not None:
        self.config["min_score"] = min_score

    # Recreate analyzer with updated config
    if self.analyzer and any(x is not None for x in [min_coverage, min_grade, min_score]):
        self.analyzer = DocumentationChecker(self.config)

    return self.analyze(path)

generate_report

generate_report(format: str = 'terminal') -> str

Generate documentation report.

Parameters:

Name	Type	Description	Default
format	str	Report format (terminal, json)	'terminal'

Returns:

Type	Description
str	Formatted report

Source code in provide/testkit/quality/documentation/fixture.py

def generate_report(self, format: str = "terminal") -> str:
    """Generate documentation report.

    Args:
        format: Report format (terminal, json)

    Returns:
        Formatted report
    """
    if not self.analyzer:
        return "No documentation analyzer available"

    if not self.results:
        return "No documentation results available"

    # Use the most recent result
    latest_result = self.results[-1]
    return self.analyzer.report(latest_result, format)

setup

setup() -> None

Set up documentation analyzer.

Source code in provide/testkit/quality/documentation/fixture.py

def setup(self) -> None:
    """Set up documentation analyzer."""
    if not INTERROGATE_AVAILABLE:
        pytest.skip("interrogate not available")

    self.analyzer = DocumentationChecker(self.config)
    self._setup_complete = True

teardown

teardown() -> None

Clean up documentation analyzer.

Source code in provide/testkit/quality/documentation/fixture.py

def teardown(self) -> None:
    """Clean up documentation analyzer."""
    self.analyzer = None
    self._setup_complete = False