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
• -t / --target-version
• -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: v1.0.0-1
    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.