blackdoc

blackdoc is a tool that applies black to code in documentation.

It was originally a rewrite of a gist and called black-doctest. In April 2020, it was renamed to blackdoc.

Installation

Dependencies:

• black
• more-itertools
• rich
• tomli
• pathspec

Install it with:

python -m pip install blackdoc

Usage

The commandline interface supports two modes: checking and inplace reformatting.

python -m blackdoc --help

In inplace reformatting mode, it will reformat the doctest lines and write them back to disk:

# on explicitly mentioned files
python -m blackdoc file1.py file2.py
# on the whole directory
python -m blackdoc .

When checking, it will report the changed files but will not write them to disk:

python -m blackdoc --check .

It is also possible to use the entrypoint script:

blackdoc --help

pre-commit

This repository defines a pre-commit hook:

hooks:
...
- repo: https://github.com/keewis/blackdoc
  rev: 3.8.0
  hooks:
  - id: blackdoc

It is recommended to pin black in order to avoid having different versions for each contributor. To automatically synchronize this pin with the version of the black hook, use the blackdoc-autoupdate-black hook:

hooks:
...
- repo: https://github.com/psf/black
  rev: 23.10.1
  hooks:
  - id: black
...
- repo: https://github.com/keewis/blackdoc
  rev: 3.8.0
  hooks:
  - id: blackdoc
    additional_dependencies: ["black==23.10.1"]
  - id: blackdoc-autoupdate-black

Note that this hook is not run on pre-commit autoupdate.