[Bug]: plot directive not handling indentation of long option strings

Bug summary

In #29644, I couldn't wrap alt text because the alt field wasn't getting properly parsed by the plot directive. Instead it yeilded something like the following for every variant

Code for reproduction

.. 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 start with 5 points
    :include-source: false

Actual outcome

Expected outcome

The alt text properly parsed so just the image shows and the alt txt is put into the html

Additional information

Matplotlib Version

dev

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:

matplotlib/lib/matplotlib/sphinxext/plot_directive.py

Lines 254 to 274 in 177f28c

    
           class PlotDirective(Directive): 
        
               """The ``.. plot::`` directive, as documented in the module's docstring.""" 
        
               has_content = True 
        
               required_arguments = 0 
        
               optional_arguments = 2 
        
               final_argument_whitespace = False 
        
               option_spec = { 
        
                   'alt': directives.unchanged, 
        
                   'height': directives.length_or_unitless, 
        
                   'width': directives.length_or_percentage_or_unitless, 
        
                   'scale': directives.nonnegative_int, 
        
                   'align': Image.align, 
        
                   'class': directives.class_option, 
        
                   'include-source': _option_boolean, 
        
                   'show-source-link': _option_boolean, 
        
                   'format': _option_format, 
        
                   'context': _option_context, 
        
                   'nofigs': directives.flag, 
        
                   'caption': directives.unchanged, 
        
                   }

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

@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:

matplotlib/lib/matplotlib/sphinxext/plot_directive.py

Line 262 in 0b7a88a

'alt': directives.unchanged,

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.

Navigation Menu

Repository navigation

[Bug]: plot directive not handling indentation of long option strings #29649

Bug summary

Code for reproduction

Actual outcome

Expected outcome

Additional information

Matplotlib Version

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

	class PlotDirective(Directive):
	"""The ``.. plot::`` directive, as documented in the module's docstring."""

	has_content = True
	required_arguments = 0
	optional_arguments = 2
	final_argument_whitespace = False
	option_spec = {
	'alt': directives.unchanged,
	'height': directives.length_or_unitless,
	'width': directives.length_or_percentage_or_unitless,
	'scale': directives.nonnegative_int,
	'align': Image.align,
	'class': directives.class_option,
	'include-source': _option_boolean,
	'show-source-link': _option_boolean,
	'format': _option_format,
	'context': _option_context,
	'nofigs': directives.flag,
	'caption': directives.unchanged,
	}

[Bug]: plot directive not handling indentation of long option strings #29649

Description

Bug summary

Code for reproduction

Actual outcome

Expected outcome

Additional information

Matplotlib Version

Activity

anntzer commented on Feb 20, 2025

story645 commented on Feb 21, 2025

tacaswell commented on Feb 21, 2025

timhoffm commented on Feb 21, 2025

story645 commented on Feb 26, 2025

QuLogic commented on Feb 27, 2025

QuLogic commented on Feb 27, 2025

QuLogic commented on Feb 27, 2025

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions