Commands

doccmd

Run commands against code blocks in the given documentation files.

This works with Markdown and reStructuredText files.

doccmd [OPTIONS] [DOCUMENT_PATHS]...

Options

-c, --command <command>

Required The command to run against code blocks.

-l, --language <languages>

Run command against code blocks for this language. Give multiple times for multiple languages. If this is not given, no code blocks are run, unless –sphinx-jinja2 is given.

--skip-marker <skip_markers>

The marker used to identify code blocks to be skipped.

By default, code blocks which come just after a comment matching ‘skip doccmd[all]: next’ are skipped (e.g. .. skip doccmd[all]: next in reStructuredText, <!— skip doccmd[all]: next –> in Markdown, or % skip doccmd[all]: next in MyST).

When using this option, those, and code blocks which come just after a comment including the given marker are ignored. For example, if the given marker is ‘type-check’, code blocks which come just after a comment matching ‘skip doccmd[type-check]: next’ are also skipped.

To skip a code block for each of multiple markers, for example to skip a code block for the type-check and lint markers but not all markers, add multiple skip doccmd comments above the code block.

--group-marker <group_markers>

The marker used to identify code blocks to be grouped.

By default, code blocks which come just between comments matching ‘group doccmd[all]: start’ and ‘group doccmd[all]: end’ are grouped (e.g. .. group doccmd[all]: start in reStructuredText, <!— group doccmd[all]: start –> in Markdown, or % group doccmd[all]: start in MyST).

When using this option, those, and code blocks which are grouped by a comment including the given marker are ignored. For example, if the given marker is ‘type-check’, code blocks which come within comments matching ‘group doccmd[type-check]: start’ and ‘group doccmd[type-check]: end’ are also skipped.

Error messages for grouped code blocks may include lines which do not match the document, so code formatters will not work on them.

--sphinx-jinja2, --no-sphinx-jinja2

Whether to parse sphinx-jinja2 blocks. This is useful for evaluating code blocks with Jinja2 templates used in Sphinx documentation. This is supported for MyST and reStructuredText files only.

Default:

False

--temporary-file-extension <temporary_file_extension>

The file extension to give to the temporary file made from the code block. By default, the file extension is inferred from the language, or it is ‘.txt’ if the language is not recognized.

--temporary-file-name-prefix <temporary_file_name_prefix>

Required The prefix to give to the temporary file made from the code block. This is useful for distinguishing files created by this tool from other files, e.g. for ignoring in linter configurations.

Default:

'doccmd'

--pad-file, --no-pad-file

Run the command against a temporary file padded with newlines. This is useful for matching line numbers from the output to the relevant location in the document. Use –no-pad-file for formatters - they generally need to look at the file without padding.

Default:

True

--pad-groups, --no-pad-groups

Maintain line spacing between groups from the source file in the temporary file. This is useful for matching line numbers from the output to the relevant location in the document. Use –no-pad-groups for formatters - they generally need to look at the file without padding.

Default:

True

--rst-extension <rst_suffixes>

Treat files with this extension (suffix) as reStructuredText. Give this multiple times to look for multiple extensions. To avoid considering any files, including the default, as reStructuredText files, use –rst-extension=..

Default:

'.rst'

--myst-extension <myst_suffixes>

Treat files with this extension (suffix) as MyST. Give this multiple times to look for multiple extensions. To avoid considering any files, including the default, as MyST files, use –myst-extension=..

Default:

'.md'

--markdown-extension <markdown_suffixes>

Files with this extension (suffix) to treat as Markdown. Give this multiple times to look for multiple extensions. By default, .md is treated as MyST, not Markdown.

Default:

Sentinel.UNSET

--max-depth <max_depth>

Maximum depth to search for files in directories.

--exclude <exclude_patterns>

A glob-style pattern that matches file paths to ignore while recursively discovering files in directories. This option can be used multiple times. Use forward slashes on all platforms.

--use-pty <use_pty_option>

Whether to use a pseudo-terminal for running commands. Using a PTY can be useful for getting color output from commands, but can also break in some environments.

‘yes’: Always use PTY (not supported on Windows).

‘no’: Never use PTY - useful when doccmd detects that it is running in a TTY outside of Windows but the environment does not support PTYs.

‘detect’: Automatically determine based on environment (default).

Default:

detect

Options:

yes | no | detect

--fail-on-parse-error, --no-fail-on-parse-error

Whether to fail (with exit code 1) if a given file cannot be parsed.

Default:

False

--fail-on-group-write, --no-fail-on-group-write

Whether to fail (with exit code 1) if a command (e.g. a formatter) tries to change code within a grouped code block. doccmd does not support writing to grouped code blocks.

Default:

True

--continue-on-error, --no-continue-on-error

Continue executing across all files even when errors occur. Collects and displays all errors found, then returns a non-zero exit code if any command invocation failed. Useful for seeing all linting errors in large projects.

Default:

False

-v, --verbose

Enable verbose output.

--version

Show the version and exit.

Arguments

DOCUMENT_PATHS

Optional argument(s)