checks.docs.DocsCheck

checks.docs.DocsCheck()

Check for documentation presence and quality.

Verifies that the package has a README file and optionally checks that public modules, classes, and functions have docstrings.

Attributes

name :

The check identifier (“docs”).

description :

Human-readable description of this check.

README_FILENAMES :

List of recognized README file names.

Configuration Options

require_readme (bool): Whether README is required. Defaults to True. check_docstrings (bool): Whether to check for docstrings in code. Defaults to False.

Examples

Run the docs check with defaults:

>>> from pathlib import Path
>>> check = DocsCheck()
>>> result = check.run(Path("."), {"enabled": True})
>>> result.name
'docs'

Enable docstring checking:

>>> config = {"enabled": True, "check_docstrings": True}
>>> result = check.run(Path("."), config)

Make README optional:

>>> config = {"enabled": True, "require_readme": False}
>>> result = check.run(Path("."), config)

Methods

Name	Description
run	Check documentation presence and quality.

run

checks.docs.DocsCheck.run(package_path, config)

Check documentation presence and quality.

Looks for a README file and optionally scans code for missing docstrings on public items.

Parameters

package_path : Path

Path to the package directory to check.

config : dict[str, Any]

Configuration dictionary with options: - require_readme (bool): Require README (default: True) - check_docstrings (bool): Check code docstrings (default: False)

Returns

: CheckResult

A CheckResult with:

: CheckResult

• OK status if all documentation requirements met

: CheckResult

• NOTE status if minor improvements suggested

: CheckResult

• WARNING status if README missing (when required)