How to make docstring format work?

[s-banach]

I have the following lines in ruff.toml:

target-version = "py39"
line-length = 88
pycodestyle.max-doc-length = 100

[format]
line-ending = "lf"
preview = true
docstring-code-format = true

I've tried adding code in my docstring in two ways:

A:

    Examples
    --------
    >>> import my_package
    >>> do_stuff(...)

B:

    Examples
    --------
    .. code-block:: python

        import my_package
        do_stuff(...)

But the ruff extension never seems to format this code in the docstring.
What am I doing wrong?

[charliermarsh]

Are you using the Ruff CLI, or the Ruff extension in your editor?

[s-banach]

Ruff extension in VSCode.
Whether I choose Ruff: Format Document or Ruff: Fix All Auto-Fixable Problems, nothing seems to happen.

[s-banach]

The extension works for formatting and linting everything else.

[charliermarsh]

I believe the code block needs to be indented:

def func():
    """Foo

    Examples
    --------

    .. code-block:: python
        import my_package
        do_stuff(...)
        x=1
    """
    ...

\cc @BurntSushi who knows the rules.

[s-banach]

I fixed the code so it builds with sphinx, but the formatter still doesn't work for me.

[BurntSushi]

Can you provide a complete source example that isn't working for you and is valid reST?

[s-banach]

I figured out that the issue is this character: \

class MyClass:
    """
    Class for doing something fun.

    * | Bullet one. This is a really really really really really\
        reallyreally really really really long line.
    * | Bullet two.

    Examples
    --------

    .. code-block:: python

        my_class = MyClass(xs=[1,2,3, 4, 5, 6, 7, 8, 9])
    """

    def __init__(self, xs: list) -> None:
        """
        Parameters
        ----------
        xs : list
            The list of x data to store in the class.
        """
        self.xs = xs

[BurntSushi]

Yeah it looks like this behavior is inherited from Black?

ruff/crates/ruff_python_formatter/src/string/docstring.rs

Lines 108 to 111 in ba71772

	// Black doesn't change the indentation of docstrings that contain an escaped newline
	if contains_unescaped_newline(docstring) {
	return normalized.fmt(f);
	}

I don't know the underlying motivation of it though. cc @MichaReiser

[MichaReiser]

The reason Black avoids normalizing docstrings containing string continuations in docstrings is that normalizing them leads to AST changes:

From the Black documentation

https://github.com/psf/black/blob/b1d17ef9a2579d10e5e31d3bb9e0a31dee95d7e9/src/black/linegen.py#L431-L443