Run `black` on python code blocks in documentation files
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
tests
.coveragerc
.gitignore
.pre-commit-config.yaml
.pre-commit-hooks.yaml
.travis.yml
LICENSE
README.md
blacken_docs.py
mypy.ini
requirements-dev.txt
setup.cfg
setup.py
tox.ini

README.md

Build Status Coverage Status

blacken-docs

Run black on python code blocks in documentation files.

install

pip install blacken-docs

usage

blacken-docs provides a single executable (blacken-docs) which will modify .rst / .md files in place.

It currently supports the following black options:

  • -l / --line-length
  • --py36
  • -S / --skip-string-normalization

Following additional parameters can be used:

  • -E / --skip-errors

blacken-docs will format code in the following block types:

(markdown)

    ```python
    def hello():
        print("hello world")
    ```

(rst)

    .. code-block:: python

        def hello():
            print("hello world")

usage with pre-commit

See pre-commit for instructions

Sample .pre-commit-config.yaml:

-   repo: https://github.com/asottile/blacken-docs
    rev: v0.3.0
    hooks:
    -   id: blacken-docs
        additional_dependencies: [black==...]

Since black is currently a moving target, it is suggested to pin black to a specific version using additional_dependencies.