This is a rst field list, I suspect (but haven't checked) that the correct way to handle multilines is to also indent the first line, see https://docutils.sourceforge.io/docs/user/rst/quickref.html#field-lists (see :Authors: in the example and the remark "Field lists are used as part of an extension syntax, such as options for directives etc.")

This is a rst field list, I suspect (but haven't checked) that the correct way to handle multilines is to also indent the first line, see https://docutils.sourceforge.io/docs/user/rst/quickref.html#field-lists

Unfortunatly that didn't work either far as I can tell (pushed this attempt to PR)

I only took a very quick look, but I don't think we are doing any of the parsing ourselves:

we are leaving that to sphinx/docutils. Maybe adding a line continuation (\) will work? If not I think this needs to go to sphinx and/or docutils.

Try an .. image:: directive with :alt:. That's a very basic docutils directive using the same definition as we do
https://github.com/docutils/docutils/blob/f704fb58904d62bf5c6d7db82a9628f29e4ed246/docutils/docutils/parsers/rst/directives/images.py#L50

If that does not work either, it's a docutils issue - either a bug or an incorrect documentation.

@timhoffm tested the following and this works as expected, with all the alt text in the alt attribute of the image

 .. image:: ../_static/anatomy.png
     :alt:
        8 squares, each showing the pattern corresponding to the hatch symbol:
        symbol '/' makes right leaning diagonals, '\\' makes left leaning diagonals,
        '|' makes vertical lines, '-' makes horizontal lines, '+' makes a grid,
        'X' makes a grid rotated 90 degrees, 'o' makes small unfilled circles,
        'O' makes large unfilled circles, '.' makes small filled circles, and '*' makes
        a star with 5 points

while this:

.. plot:: _embedded_plots/hatch_classes.py
   :alt:
      8 squares, each showing the pattern corresponding to the hatch symbol:
      symbol '/' makes right leaning diagonals, '\\' makes left leaning diagonals,
      '|' makes vertical lines, '-' makes horizontal lines, '+' makes a grid,
      'X' makes a grid rotated 90 degrees, 'o' makes small unfilled circles,
      'O' makes large unfilled circles, '.' makes small filled circles, and '*' makes
      a star with 5 points

generates this output where there's alt text then directive information then alt text again, which to me points to a parsing error in .. plot::

It is strange, because Image defines alt as unchanged, but so do we:

So there should be no difference in parsing.

It must be a bug with has_content = True for the directive (since image doesn't have content, but plot does.)

For reasons I don't quite understand, the plot directive renders the plots, and then templates it out into new reST, which is inserted into the parser after it. This path through text again doesn't handle multi-line input and is what causes the breakage.