blackdoc 0.4.5


pip install blackdoc

  Latest version

Released: Oct 21, 2025


Meta
Author: Justus Magin
Requires Python: >=3.10

Classifiers

Development Status
  • 3 - Alpha

Environment
  • Console

Intended Audience
  • Developers

Operating System
  • OS Independent

Programming Language
  • Python
  • Python :: 3.10
  • Python :: 3.11
  • Python :: 3.12
  • Python :: 3.13
  • Python :: 3 :: Only

Topic
  • Documentation
  • Software Development :: Documentation
  • Software Development :: Libraries :: Python Modules
  • Software Development :: Quality Assurance
https://github.com/keewis/blackdoc/actions/workflows/ci.yml/badge.svg?branch=main https://img.shields.io/badge/code%20style-black-000000.svg Documentation Status

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:

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.

Wheel compatibility matrix

Platform Python 3
any

Files in release

Extras: None
Dependencies:
black (>=24.4)
more-itertools
tomli
pathspec
rich