selfdoc v0.15.1 /selfdoc.check
Updated
On this page

Check command module that validates directive resolution, measures API documentation coverage, runs 15 SEO lint rules, and detects stale descriptions.

#selfdoc.check

#selfdoc.check

Check command -- validate directives and report documentation coverage.

Scans docs/ templates for directives, attempts to resolve each one, and reports per-directive status (OK or FAILED). For all supported languages, computes coverage: how many public/exported symbols are referenced by directives vs. the total in source files.

#DirectiveResult

Result of validating a single directive.

#ResolvedDirective

A successfully resolved directive with its output content.

#CoverageStats

Coverage of public symbols by directives.

#LintResult

A single lint diagnostic (e.g. SEO warning).

#CheckResult

Aggregate result of check_docs().

#_validate_directives

python
def _validate_directives(docs_dict, resolver, valid_names, file_prefix='', collect_resolved=False)

Validate directives across a set of documentation templates.

Parses directives from each template, attempts resolution, and records per-directive OK/FAILED results.

Args:

  • docs_dict: Dict from resolve_all_docs mapping rel_path to

(frontmatter, resolved, raw_content, fm_line_count).

  • resolver: Directive resolver callable.
  • valid_names: Set of valid directive names for parse-time validation.
  • file_prefix: String prepended to rel_path in results (e.g. "[0.1.0] ").
  • collect_resolved: If True, collect successfully resolved directives

with attrs into a list for coverage tracking.

Returns:

  • (directive_results, resolved_directives) where directive_results is
  • a list of DirectiveResult and resolved_directives is a list of
  • ResolvedDirective (empty if collect_resolved is False).

#check_docs

python
def check_docs(dir_path='.', config=None, dry_run=False)

Validate all directives in docs templates and report coverage.

Scans docs/ for .md templates, parses directives, attempts to resolve each one, and computes coverage for Python projects.

Args:

  • dir_path: Project root directory.
  • config: Pre-loaded config dict (if None, loads from selfdoc.json).
  • dry_run: If True, report staleness without writing hashes to disk.

Returns:

  • CheckResult with per-directive results and optional coverage stats.

#_token_text_lines

python
def _token_text_lines(tok)

Extract text lines from a content-bearing token.

Returns a list of strings (one per source line) so the caller can compute per-line offsets from tok.start.

#_check_version_consistency

python
def _check_version_consistency(config, dir_path)

Check version consistency between config and project manifest.

VER002: config["version"] differs from detected project version. VER003: versions array last entry doesn't match config["version"].

#_run_lints

python
def _run_lints(all_docs, docs_dir, resolver, config)

Run lint checks on documentation templates.

Args:

  • all_docs: Dict from resolve_all_docs mapping rel_path to

(frontmatter, resolved, raw_content, fm_line_count).

  • docs_dir: Absolute path to the docs directory.
  • resolver: Directive resolver callable.
  • config: Project configuration dict.

Returns a list of LintResult diagnostics covering SEO best practices: multiple H1s, heading level gaps, empty alt text, title length, missing base_url, and missing description.

#_parse_hex_color

python
def _parse_hex_color(hex_color)

Parse a #RRGGBB hex color to (R, G, B) tuple of 0-255 ints.

#_relative_luminance

python
def _relative_luminance(rgb)

Compute WCAG 2.1 relative luminance from an (R, G, B) tuple.

#_contrast_ratio

python
def _contrast_ratio(rgb1, rgb2)

Compute WCAG 2.1 contrast ratio between two RGB colors.

#_extract_css_vars

python
def _extract_css_vars(css_block)

Extract CSS custom properties from a block of CSS text.

Returns a dict mapping property names (e.g. '--bg') to values.

#_check_contrast

python
def _check_contrast(lints, config, base_dir)

Check WCAG 2.1 contrast ratios for theme colors (SEO012).

Parses the theme CSS for custom properties and verifies critical foreground/background pairs meet minimum contrast ratios.

#_check_pairs

python
def _check_pairs(lints, css_vars, pairs, mode_prefix, css_file='theme CSS')

Check contrast ratio for each pair and emit SEO012 if below threshold.

#_is_skeleton_page

python
def _is_skeleton_page(frontmatter)

Return True if the page is a skeleton auto-generated page.

A page is "skeleton" when it has generated: true AND its description still matches the default auto-generated pattern. A generated page whose description has been customized counts as documented (someone edited it).

#_compute_coverage

python
def _compute_coverage(config, base_dir, resolved_directives, source_entries, all_docs=None)

Count public symbols in source files vs. those documented by directives.

Multi-language: iterates over all source entries, using each entry's extractor to discover public symbols and resolve file paths. Two-tier tracking:

  • "referenced": symbol appears in ANY directive's resolved output
  • "documented": symbol appears on a non-skeleton page (hand-written or

generated with a customized description)

Files whose module path matches a gen.exclude pattern are skipped so that intentionally-internal modules do not drag down coverage.

Args:

  • source_entries: List of SourceEntry objects (each with path, language,

extractor). Replaces the old single-extractor parameter.

  • all_docs: Dict from resolve_all_docs mapping rel_path to

(frontmatter, resolved, raw_content, fm_line_count). When provided, enables two-tier skeleton page detection.

#_color

python
def _color(text, code)

Wrap text in ANSI escape codes when color output is enabled.

#filter_lints

python
def filter_lints(lints, ignore_codes)

Return lints excluding those whose code is in ignore_codes.

Args:

  • lints: List of LintResult objects.
  • ignore_codes: Set or collection of code strings to suppress.

Returns:

  • Filtered list of LintResult objects.
python
def print_results(result)

Print check results to stdout in a human-readable format.

Args:

  • result: CheckResult to print.

#check_unified

python
def check_unified(dir_path='.', config=None, dry_run=False)

Check all constituent projects in a unified build.

Iterates over each project in the unified config section, loads its own selfdoc.json, and runs check_docs on it. Errors are prefixed with the project slug for clear attribution.

Also checks the docs-site's own content (the common pages).

Args:

  • dir_path: The docs-site's project root directory.
  • config: Pre-loaded config dict (if None, loads from selfdoc.json).
  • dry_run: If True, report staleness without writing hashes to disk.

Returns:

  • CheckResult with aggregated results from all projects.