Commands

doccmd

Run commands against code blocks in the given documentation files.

This works with Markdown and reStructuredText files.

doccmd [OPTIONS] [DOCUMENT_PATHS]...

Options

-l, --language <languages>

Required Run command against code blocks for this language. Give multiple times for multiple languages.

-c, --command <command>

Required

--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'

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

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

--version

Show the version and exit.

-v, --verbose

Enable verbose output.

--use-pty

Use a pseudo-terminal for running commands. This can be useful e.g. to get color output, but can also break in some environments. Not supported on Windows.

Default:

'--detect-use-pty'

--no-use-pty

Do not use a pseudo-terminal for running commands. This is useful when doccmd detects that it is running in a TTY outside of Windows but the environment does not support PTYs.

Default:

'--detect-use-pty'

--detect-use-pty

Automatically determine whether to use a pseudo-terminal for running commands.

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.

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

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

Arguments

DOCUMENT_PATHS

Optional argument(s)