great-docs lint

Lint documentation quality for your package.

great-docs lint [OPTIONS]

Analyzes your package’s public API for documentation issues including missing docstrings, broken cross-references, inconsistent formatting, malformed directives, and stale version annotations.

• Checks performed:
• missing-docstring Public exports or methods without docstrings
• broken-xref %seealso references to unknown symbols
• style-mismatch Docstrings not matching configured style (numpy/google/sphinx)
• unknown-directive Unrecognized %directive names
• empty-seealso %seealso entries with empty references
• stale-badge Version badges far behind latest release
• stale-callout Version callouts that are very old
• stale-upcoming upcoming: frontmatter for already-released versions

Full --help output

Usage: great-docs lint [OPTIONS]

  Lint documentation quality for your package.

  Analyzes your package's public API for documentation issues including
  missing docstrings, broken cross-references, inconsistent formatting,
  malformed directives, and stale version annotations.

  Checks performed:
    • missing-docstring    Public exports or methods without docstrings
    • broken-xref          '%seealso' references to unknown symbols
    • style-mismatch       Docstrings not matching configured style (numpy/google/sphinx)
    • unknown-directive    Unrecognized '%directive' names
    • empty-seealso        '%seealso' entries with empty references
    • stale-badge          Version badges far behind latest release
    • stale-callout        Version callouts that are very old
    • stale-upcoming       'upcoming:' frontmatter for already-released versions

  Examples:
    great-docs lint                                # Run all checks
    great-docs lint --check stale-versions         # Only check for stale annotations
    great-docs lint --check docstrings             # Only check for missing docstrings
    great-docs lint --check cross-refs --check style
    great-docs lint --json                         # JSON output for CI
    great-docs lint --json | jq '.issues[] | select(.severity == "error")'

Options:
  --project-path DIRECTORY        Path to your project root directory
                                  (default: current directory)
  --check [docstrings|cross-refs|style|directives|stale-versions]
                                  Run only specific checks (can be repeated).
                                  Default: all checks.
  --json                          Output results as JSON for CI integration
  --help                          Show this message and exit.

Options

--project-path: DIRECTORY

Path to your project root directory (default: current directory)

--check: CHOICE

Run only specific checks (can be repeated). Default: all checks.

--json

Output results as JSON for CI integration

Examples

  great-docs lint                                # Run all checks
  great-docs lint --check stale-versions         # Only check for stale annotations
  great-docs lint --check docstrings             # Only check for missing docstrings
  great-docs lint --check cross-refs --check style
  great-docs lint --json                         # JSON output for CI
  great-docs lint --json | jq '.issues[] | select(.severity == "error")'