ruffen-docs

Run ruff on Python code blocks in documentation files.

Installation

Use pip:

python -m pip install ruffen-docs

Python 3.10 to 3.14 supported.

ruff 0.14.1+ supported.

pre-commit hook

You can also install ruffen-docs as a pre-commit hook. Add the following to the repos section of your .pre-commit-config.yaml file (docs):

-   repo: https://github.com/ulgens/ruffen-docs
    rev: ""  # replace with latest tag on GitHub
    hooks:
    -   id: ruffen-docs
        additional_dependencies:
        - ruff==0.14.1

Then, reformat your entire project:

pre-commit run ruffen-docs --all-files

Since ruff is a moving target, it’s best to pin it in additional_dependencies, and upgrade as appropriate. If you have ruff installed as another hook, you can automate upgrading this pinned hook using sync-pre-commit-deps.

Usage

ruffen-docs is a command line tool that rewrites documentation files in place. It supports Markdown, reStructuredText, and LaTex files. Additionally, you can run it on Python files to reformat Markdown and reStructuredText within docstrings.

Run ruffen-docs with the filenames to rewrite:

ruffen-docs README.rst

If any file is modified, ruffen-docs exits nonzero.

ruffen-docs does not have any ability to recurse through directories. Use the pre-commit integration, globbing, or another technique for applying to many files. For example, with git ls-files | xargs:

git ls-files -z -- '*.md' | xargs -0 ruffen-docs

…or PowerShell’s ForEach-Object:

git ls-files -- '*.md' | %{ruffen-docs $_}

ruffen-docs currently passes the following options through to ruff:

• -l / --line-length
• --preview
• --pyi
• -S / --skip-string-normalization
• -t / --target-version

It also has the below extra options:

• --check - Don’t modify files but indicate when changes are necessary with a message and non-zero return code.
• -E / --skip-errors - Don’t exit non-zero for errors from Black (normally syntax errors).
• --rst-literal-blocks - Also format literal blocks in reStructuredText files (more below).

History

ruffen-docs is a fork of blacken-docs. The project is currently maintained by @ulgens.

Supported code block formats

ruffen-docs formats code blocks matching the following patterns.

Markdown

In “python” blocks:

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

And “pycon” blocks:

```pycon

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

```

Prevent formatting within a block using ruffen-docs:off and ruffen-docs:on comments:

<!-- ruffen-docs:off -->
```python
# whatever you want
```
<!-- ruffen-docs:on -->

Within Python files, docstrings that contain Markdown code blocks may be reformatted:

def f():
    """docstring here

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

reStructuredText

In “python” blocks:

.. code-block:: python

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

In “pycon” blocks:

.. code-block:: pycon

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

Prevent formatting within a block using ruffen-docs:off and ruffen-docs:on comments:

.. ruffen-docs:off

.. code-block:: python

    # whatever you want

.. ruffen-docs:on

Use --rst-literal-blocks to also format literal blocks:

An example::

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

Literal blocks are marked with :: and can be any monospaced text by default. However Sphinx interprets them as Python code by default. If your project uses Sphinx and such a configuration, add --rst-literal-blocks to also format such blocks.

Within Python files, docstrings that contain reStructuredText code blocks may be reformatted:

def f():
    """docstring here

    .. code-block:: python

        print("hello world")
    """

LaTeX

In minted “python” blocks:

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

In minted “pycon” blocks:

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

In PythonTeX blocks:

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

Prevent formatting within a block using ruffen-docs:off and ruffen-docs:on comments:

% ruffen-docs:off
\begin{minted}{python}
# whatever you want
\end{minted}
% ruffen-docs:on