blacken-docs is a command-line tool that formats Python code blocks within various documentation files (Markdown, reStructuredText, LaTeX, and Python docstrings) using the opinionated `Black` formatter. It operates by rewriting files in place. The library is currently at version 1.20.0, actively maintained, and releases occur periodically to support new Python versions and `Black` features.
pip install blacken-docsNo compatibility data collected yet for this library.
Install `blacken-docs` and run it from the command line on individual files or using glob patterns. The most common and recommended usage is as a `pre-commit` hook to automate formatting documentation code blocks.
When using `blacken-docs` as a `pre-commit` hook, always specify the `black` version in `additional_dependencies` (e.g., `additional_dependencies: ['black==24.4.0']`) in your `.pre-commit-config.yaml` to ensure consistent formatting.
This behavior is by design, indicating that files needed formatting. In CI/CD, this usually means the job failed and needs the formatted changes committed. Use the `--check` option to only check for changes without modifying files, returning a non-zero code if changes are needed. The `--skip-errors` (or `-E`) option can prevent non-zero exits for Black's internal syntax errors.
If `Black` complains about `...` not being syntactically valid in a code block, replace it with `# ...` or ensure the code block is fully syntactically valid without needing an ellipsis.
Ensure the code within the block is valid Python syntax. If using `pycon` blocks with `>>>` prompts, ensure your `blacken-docs` version is 1.9.0 or newer, which added explicit support for these.
Standardize the `Black` version across all environments. For `pre-commit`, explicitly pin `Black` in `additional_dependencies` of the `blacken-docs` hook (e.g., `additional_dependencies: ['black==24.4.0']`). Ensure your local `black` installation matches this version, or exclusively rely on `pre-commit` for formatting.