Usage: doccmd [OPTIONS] [DOCUMENT_PATHS]...

  Run commands against code blocks in the given documentation files.

  This works with Markdown and reStructuredText files.

Options:
  -l, --language TEXT             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.
  -c, --command TEXT              [required]
  --temporary-file-extension TEXT
                                  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 TEXT
                                  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; required]
  --skip-marker TEXT              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 TEXT             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: pad-file]
  --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: pad-groups]
  --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 TEXT            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 TEXT           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 TEXT       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 INTEGER RANGE       Maximum depth to search for files in
                                  directories.  [x>=1]
  --exclude TEXT                  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: no-fail-on-
                                  parse-error]
  --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: fail-on-group-write]
  --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: no-
                                  sphinx-jinja2]
  --help                          Show this message and exit.
