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. Also reports outdated keys in great-docs.yml, pages that fall back to the default search description, and front matter values of the wrong type.

• Checks performed:
• config-key great-docs.yml keys spelled the old way, or ignored
• missing-docstring Public exports or methods without docstrings
• broken-xref %seealso references to unknown symbols
• ambiguous-xref References to a short name two objects claim
• unread-source A linked source’s inventory could not be read
• style-mismatch Docstrings not matching configured style (numpy/google/sphinx)
• unknown-directive Unrecognized %directive names
• stale-badge Version badges far behind latest release
• stale-callout Version callouts that are very old
• stale-upcoming upcoming: frontmatter for already-released versions
• default-description Pages with no opening paragraph to describe them in search
• front-matter great-docs front matter keys set to a value of the wrong type

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. Also reports outdated
  keys in great-docs.yml, pages that fall back to the default search
  description, and front matter values of the wrong type.

  Checks performed:
    • config-key           great-docs.yml keys spelled the old way, or ignored
    • missing-docstring    Public exports or methods without docstrings
    • broken-xref          '%seealso' references to unknown symbols
    • ambiguous-xref       References to a short name two objects claim
    • unread-source        A linked source's inventory could not be read
    • style-mismatch       Docstrings not matching configured style (numpy/google/sphinx)
    • unknown-directive    Unrecognized '%directive' names
    • stale-badge          Version badges far behind latest release
    • stale-callout        Version callouts that are very old
    • stale-upcoming       'upcoming:' frontmatter for already-released versions
    • default-description  Pages with no opening paragraph to describe them in search
    • front-matter         great-docs front matter keys set to a value of the wrong type

  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 config                 # Only check great-docs.yml keys
    great-docs lint --check descriptions           # Only check search descriptions
    great-docs lint --check front-matter           # Only check front matter value types
    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 [config|docstrings|cross-refs|style|directives|stale-versions|descriptions|front-matter]
                                  Run only specific checks (can be repeated).
                                  Default: all checks.
  --json                          Output results as JSON for CI integration
  --config FILE                   Path to the project configuration file
  --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

--config: FILE

Path to the project configuration file

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 config                 # Only check great-docs.yml keys
  great-docs lint --check descriptions           # Only check search descriptions
  great-docs lint --check front-matter           # Only check front matter value types
  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")'