doccmd 2024.9.11.5

Run commands against code blocks in reStructuredText and Markdown files.

doccmd

A command line tool for running commands against documentation files.

• Installation

  • With pip

  • With Homebrew (macOS, Linux, WSL)

• Usage example

• What does it work on?

• Full documentation

Installation

With pip

Requires Python 3.11+.

pip install doccmd

With Homebrew (macOS, Linux, WSL)

Requires Homebrew.

brew tap adamtheturtle/doccmd
brew install doccmd

Usage example

# Run mypy against the Python code blocks in README.md and CHANGELOG.rst
$ doccmd --language=python --command="mypy" README.md CHANGELOG.rst

# Run gofmt against the Go code blocks in README.md
# This will modify the README.md file in place
$ doccmd --language=go --command="gofmt -w" README.md

# or type less...
$ doccmd -l python -c mypy README.md CHANGELOG.rst

What does it work on?

• reStructuredText (.rst)

.. code-block:: shell

   echo "Hello, world!"

• Markdown (.md)

```shell
echo "Hello, world!"
```

• MyST (.md with MyST syntax)

```{code-block} shell
echo "Hello, world!"
```

• Want more? Open an issue!

TODO:

• Release pre-commit hook

• Verbose mode… “Running command “X” against README.rst example from line …”

• Option to not delete file

• Document https://sybil.readthedocs.io/en/latest/rest.html#skipping-examples on docrun, and make it work

Full documentation

See the full documentation.