blacken-docs

What it is and what it does

blacken-docs is a command-line tool that runs Black's code formatter on Python code blocks found within documentation files. It recognizes Python code in Markdown fenced blocks (```python and ```pycon), reStructuredText code-block directives, LaTeX minted and pycode environments, and Python docstrings. The tool rewrites files in place and exits with a non-zero status if any changes were made, making it suitable for CI/CD pipelines and pre-commit hooks.

The package depends solely on black and is designed to keep documentation examples in sync with your project's code style. It supports Black's key options (line length, target version, string normalization, preview mode) and adds its own flags for dry-run checking, error suppression, and optional reStructuredText literal-block formatting. It does not recurse directories—you provide explicit file paths or use shell globbing and pre-commit integration to apply it across many files.

Use it for:

• Enforce consistent code style in README and API documentation examples alongside your main codebase formatting.
• Integrate into pre-commit hooks to automatically reformat code blocks in pull requests before commit.
• Verify documentation code blocks are syntactically valid and properly formatted as part of CI checks.
• Reformat Python code examples embedded in docstrings when refactoring or upgrading Black versions.
• Maintain LaTeX documentation with minted code blocks in a consistent style with your project's Black config.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Applies Black code formatting to Python code blocks embedded in documentation files (Markdown, reStructuredText, LaTeX) and Python docstrings.

Yes. This is a lightweight, actively maintained tool with no security vulnerabilities and a single stable dependency. Install it if you maintain documentation with embedded Python code and want to keep those examples formatted consistently with Black. The pre-commit integration makes it a natural fit for projects already using Black.

Install

blacken-docs on PyPI

pip install blacken-docs

uv add blacken-docs

poetry add blacken-docs

Installing blacken-docs

Before you install

Low friction: single runtime dependency on black, pure Python wheel, actively maintained with recent releases. Supports Python 3.9 to 3.14.

License in practice

MIT license permits unrestricted use, modification, and distribution with minimal restrictions—suitable for any project type.

Quickstart

pip install blacken-docs
blacken-docs README.rst

# Or in a pre-commit hook:
# Add to .pre-commit-config.yaml:
# - repo: https://github.com/adamchainz/blacken-docs
#   rev: "1.20.0"
#   hooks:
#   - id: blacken-docs
#     additional_dependencies:
#     - black==22.12.0

Requires black 22.1.0 or later; best practice is to pin black version in pre-commit additional_dependencies to avoid format drift.

Verify before relying

• Whether the tool correctly handles edge cases in mixed-format documentation (e.g., nested code blocks or unusual indentation).
• Performance characteristics when processing large documentation sets or files with many code blocks.

Package facts

Evidence: blacken_docs-1.20.0-py3-none-any.whl

Tags

More Documentation packages