# great-docs check-examples


Check that Python code examples execute without errors.


``` bash
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.


<span class="gd-details-chevron" aria-hidden="true"></span>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

``` bash
  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
```