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