DOC: Show and correct default alignment parameters in text.py

[jsalsman]

For issue [Doc]: text alignment defaults: closes #27345

PR summary

Show the default text horizontalalignment/ha (left) and verticalalignment/va (baseline) in the parameter docstrings (and the associated gallery page), and correct an error falsely claiming that bottom was the vertical default.

PR checklist

• "closes #0000" is in the body of the PR description to link the related issue
• [N/A] new and changed code is tested
• Plotting related features are demonstrated in https://matplotlib.org/devdocs/gallery/text_labels_and_annotations/text_alignment.html
• [N/A] New Features and API Changes are noted with a directive and release note
• Documentation complies with general and docstring guidelines

[github-actions]

Thank you for opening your first PR into Matplotlib!

If you have not heard from us in a week or so, please leave a new comment below and that should bring it to our attention. Most of our reviewers are volunteers and sometimes things fall through the cracks.

You can also join us on gitter for real-time discussion.

For details on testing, writing docs, and our review process, please see the developer guide

We strive to be a welcoming and open project. Please follow our Code of Conduct.

[StefRe]

There is no default value here as the align parameter is not optional (i.e. you can't call set_horizontalalignment() and expect that it sets the alignement to left)

[jsalsman]

But if you don't call the setter, the value is left. How to convey that in the docs?

[StefRe]

The default values are (implicitly) documented in the __init__ method (class signature).

Further, matplotlib follows numpydoc conventions:

When a parameter can only assume one of a fixed set of values, those values can be listed in braces, with the default appearing first:

order : {'C', 'F', 'A'}
   Description of `order`.

So the explicit description of the default value is not required in this case, we'd just need to move the baseline entry for verticalalignment to the first position.

[jsalsman]

move the baseline entry for verticalalignment to the first position.

Done.

[StefRe]

same as above: there is no default value here as the align parameter is not optional.

[ksunden]

This is a little complicated because these do have a default value in __init__, but not in their set_<attr> method... but the way the docstring is constructed takes the descriptions from the setters.

I think we may be able to do some appending of default values where that table gets constructed (though I have not looked at all the places that code is used/all the docstrings it interacts with, which could result in confusing double Default: ... sections if there already is one). However, it is several layers deep in how it is constructed, so may not be trivial to do so (not the least because you somehow need to thread through where to take the defaults from, and that isn't there now:

• _docstring._ArtistPropertiesSubstitution
• `_docstring._ArtistKwdocLoader
• artist.kwdoc
• artist.ArtistInspector
• artist.ArtistInspector.pprint_setters

So in short, not trivial, but probably possible... would need careful consideration of how these pieces interact though (and would include changing some "public" (though potentially should be private) APIs to do it).

See also #22699 which provides a mechanism for potentially adding/modifying the info that gets put into the table. (It is currently marked as "proof of concept", and has not been merged, though has had some positive response)

[jsalsman]

This is a little complicated because these do have a default value in __init__, but not in their set_<attr> method... but the way the docstring is constructed takes the descriptions from the setters.

@ksunden @StefRe as an interim measure, how would you feel about giving the setter methods the same defaults as those parameters?

[StefRe]

how would you feel about giving the setter methods the same defaults as those parameters?

I think making an API change just for documentation purposes is not the way to go (also, a setter without an argument isn't a setter anymore, I'd expect such a method be called reset...).

[jsalsman]

... probably possible... would need careful consideration of how these pieces interact though (and would include changing some "public" (though potentially should be private) APIs to do it).

@ksunden as @StefRe objected to that, I reverted back to the way he likes it. While setting out along your advice, I came across the mystery as to why the docstring at https://github.com/matplotlib/matplotlib/blob/main/lib/matplotlib/text.py#L125 doesn't appear anywhere in https://matplotlib.org/devdocs/api/_as_gen/matplotlib.pyplot.text.html -- so that led me to discover the top of that doc page comes from https://github.com/matplotlib/matplotlib/blob/main/lib/matplotlib/axes/_axes.py#L633 so I clarified the alignment parameter defaults there instead of the table.

[jsalsman]

Review please?

[oscargus]

Thanks @jsalsman and congratulations on your first merged PR! Hope to see you around!