Run `black` on python code blocks in documentation files
Clone or download
Pull request Compare This branch is 11 commits behind asottile:master.
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.2.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.