docstring code formatter:Allow customizing to-be-formatted directives

[flying-sheep]

Currently the supported directives are hardcoded here:

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

Lines 1082 to 1087 in 9180635

	static DIRECTIVE_START: LazyLock<Regex> = LazyLock::new(|| {
	Regex::new(
	r"(?m)^\s*\.\. \s*(?i:code-block|sourcecode)::\s*(?i:python|py|python3|py3)$",
	)
	.unwrap()
	});

Would be great to be able to customize the list of directives, so e.g. .. plot:: can be supported.

I’d suggest to only allow adding directives that have code in the body, i.e. doing docstring-code-format-extra-directives = ["plot"] would format the last line here:

.. plot::
   :foo: bar

   import baz

but not something like this:

.. plot::
   import baz

in reStructuredText semantics, the first import baz is in the body of the block (the block also has options that we can ignore), while the second one is a positional argument to the block.

[MichaReiser]

Reading through the documentation, I see cases where what follows isn't guaranteed to be code.

.. plot:: path/to/plot.py

   The plot caption.

In addition, it limits how we can evolve the docstring formatting in the future because we know less about the surrounding context. Without a custom regex, we know exactly when and where the docstrings get formatted and if making a certain change doesn't cause any issues in those contexts.

That's why I'm very hesitant to support dynamic code blocks.