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, .txt, .text, and .py files in place.

For example:

python3 blacken_docs.py test-docs/README.md

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

(markdown)

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

(markdown pycon)

    ```pycon

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

    ```

RST

(rst)

    .. code-block:: python

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

(rst pycon)

    .. code-block:: pycon

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

Latex

(latex)

\begin{minted}{python}
def hello():
    print("hello world")
\end{minted}

(latex pycon)

\begin{minted}{pycon}
>>> def hello():
...     print("hello world")
...
\end{minted}

(latex with pythontex)

\begin{pycode}
def hello():
    print("hello world")
\end{pycode}

Python

(markdown/rst in python docstrings)

def f():
    """docstring here

    .. code-block:: python

        print("hello world")

    ```python
    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.12.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.