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 / .tex files in place.

If a file is modified, blacken-docs exits nonzero.

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")
    ```

(markdown pycon)

    ```pycon

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

    ```

(rst)

    .. code-block:: python

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

(rst pycon)

    .. code-block:: pycon

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

(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}

(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.