Documentation: mention tools that can do doctests formatting

[KelSolaar]

Is your feature request related to a problem? Please describe.

Black currently does not format Doctests in Docstrings. This issues was reported in #745 which was superseeded by #144.

As the latter was closed though, nothing was done about the Doctests.

Describe the solution you'd like

I would be keen for black to format Doctest.

For example, given the following Python Doctests code:

    >>> XYZ = np.array([0.20654008, 0.12197225, 0.05136952])
    >>> LMS_to_LMS_p_callable = lambda x: x ** 0.43
    >>> matrix_XYZ_to_LMS = np.array(
    ...     [[0.4002, 0.7075, -0.0807],
    ...      [-0.2280, 1.1500, 0.0612],
    ...      [0.0000, 0.0000, 0.9184]])
    >>> matrix_LMS_p_to_Iab = np.array(
    ...     [[0.4000, 0.4000, 0.2000],
    ...      [4.4550, -4.8510, 0.3960],
    ...      [0.8056, 0.3572, -1.1628]])
    >>> XYZ_to_Iab(
    ...     XYZ, LMS_to_LMS_p_callable, matrix_XYZ_to_LMS, matrix_LMS_p_to_Iab)

black could produce the following output:

    >>> XYZ = np.array([0.20654008, 0.12197225, 0.05136952])
    >>> LMS_to_LMS_p_callable = lambda x: x**0.43
    >>> matrix_XYZ_to_LMS = np.array(
    ...     [
    ...         [0.4002, 0.7075, -0.0807],
    ...         [-0.2280, 1.1500, 0.0612],
    ...         [0.0000, 0.0000, 0.9184],
    ...     ]
    ... )
    >>> matrix_LMS_p_to_Iab = np.array(
    ...     [
    ...         [0.4000, 0.4000, 0.2000],
    ...         [4.4550, -4.8510, 0.3960],
    ...         [0.8056, 0.3572, -1.1628],
    ...     ]
    ... )
    >>> XYZ_to_Iab(
    ...     XYZ, LMS_to_LMS_p_callable, matrix_XYZ_to_LMS, matrix_LMS_p_to_Iab
    ... )

Describe alternatives you've considered

I'm manually formatting the code.

Additional context

N/A

[felix-hilden]

Thank you for opening the discussion again. Personally, after #2150, #3087 and the like, I'm increasingly hesitant to push for more docstring changes. To be fair though, formatting docstrings could be less controversial than us choosing a strict docstring style. Since doctests are code, would this be more appropriate as a dedicated tool wrapping Black?

[KelSolaar]

Since doctests are code, would this be more appropriate as a dedicated tool wrapping Black?

This is a good point!

[adam-grant-hendry]

Question: isn't this already supported by blacken-docs?

[adam-grant-hendry]

Question: isn't this already supported by blacken-docs?

After posting this, I realized that extension only works on documentation files (.rst/.md/.tex), but not directly on python files.

[adam-grant-hendry]

However, blackdoc works on python files. Depending on where you are placing doctests, you may need both packages.

[KelSolaar]

Oh awesome! I will give it a stab, that would be certainly worth showcasing in the black docs/website!

[felix-hilden]

I'd be willing to consider advertising some of these tools in, say, our "integrations"!