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.
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")
(rst pycon)
.. code-block:: pycon
>>> def hello():
... print("hello world")
...
(latex)
\begin{minted}{python}
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.9.2
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.
