great-docs check-examples

Check that Python code examples execute without errors.

great-docs check-examples [OPTIONS] [PATHS]...

Renders .qmd files and docstring examples via Quarto, reporting which cells succeed and which error. Every cell is executed even if earlier cells fail (Quarto’s error: true mode).

Requires Quarto to be installed (https://quarto.org).

PATHS are optional files or directories to check. When omitted, the entire project is scanned.

Full --help output

Usage: great-docs check-examples [OPTIONS] [PATHS]...

  Check that Python code examples execute without errors.

  Renders .qmd files and docstring examples via Quarto, reporting which cells
  succeed and which error. Every cell is executed even if earlier cells fail
  (Quarto's error: true mode).

  Requires Quarto to be installed (https://quarto.org).

  PATHS are optional files or directories to check. When omitted, the entire
  project is scanned.

  Examples:
    great-docs check-examples
    great-docs check-examples reference/
    great-docs check-examples guide/getting-started.qmd --verbose
    great-docs check-examples --json-output
    great-docs check-examples --parallel --jobs 4
    great-docs check-examples --no-docstrings --timeout 60

Options:
  --project-path DIRECTORY  Path to your project root directory (default:
                            current directory)
  --timeout INTEGER         Per-cell timeout in seconds (default: 30)
  --json-output             Output results as JSON
  -v, --verbose             Show full tracebacks in console output
  --include TEXT            Glob pattern to filter which files to check
                            (relative to the docs source directory)
  --exclude TEXT            Glob pattern to exclude files from checking
                            (relative to the docs source directory)
  --no-docstrings           Skip docstring example checking
  --docstrings-only         Only check docstring examples, skip .qmd files
  --parallel                Run pages concurrently (each in its own
                            subprocess/kernel)
  -j, --jobs INTEGER        Number of concurrent pages (implies --parallel if
                            > 1)
  --log-file PATH           Where to write full tracebacks (default: .great-
                            docs/check-examples.log)
  --config FILE             Path to the project configuration file
  --help                    Show this message and exit.

Arguments

PATHS: PATH

Optional.

Options

--project-path: DIRECTORY

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

--timeout: INTEGER = 30

Per-cell timeout in seconds (default: 30)

--json-output

Output results as JSON

-v, --verbose

Show full tracebacks in console output

--include: TEXT

Glob pattern to filter which files to check (relative to the docs source directory)

--exclude: TEXT

Glob pattern to exclude files from checking (relative to the docs source directory)

--no-docstrings

Skip docstring example checking

--docstrings-only

Only check docstring examples, skip .qmd files

--parallel

Run pages concurrently (each in its own subprocess/kernel)

-j, --jobs: INTEGER = 1

Number of concurrent pages (implies --parallel if > 1)

--log-file: PATH

Where to write full tracebacks (default: .great-docs/check-examples.log)

--config: FILE

Path to the project configuration file

Examples

  great-docs check-examples
  great-docs check-examples reference/
  great-docs check-examples guide/getting-started.qmd --verbose
  great-docs check-examples --json-output
  great-docs check-examples --parallel --jobs 4
  great-docs check-examples --no-docstrings --timeout 60