Combine withEffect PathEffect definitions. #15515
Conversation
There was a problem hiding this comment.
For some reason, docstring inheritance does not work for the draw_path() method of the generated class. Compare
https://matplotlib.org/devdocs/api/patheffects_api.html#matplotlib.patheffects.withStroke.draw_path
and
https://9440-7439715-gh.circle-artifacts.com/0/home/circleci/project/doc/build/html/api/patheffects_api.html#matplotlib.patheffects.withStroke.draw_path
Apart from that, I have the concern that this is obscuring things more. withStroke = _make_with_effect(Stroke) does in no way indicate that withStroke is actually a class. This needs better naming and documentation.
|
Re docs: good catch, this is actually a limitation of the implementation of inspect.getdoc (which can be fixed at least in this case), I'll open a bug report on the python tracker. In the meantime I just inherited the docstring manually. |
|
What about |
|
Sounds good, changed accordingly. |
|
(the docstring inheritance issue is at https://bugs.python.org/issue38603) |
lib/matplotlib/patheffects.py
Outdated
|
|
||
| withEffect.__name__ = f"with{effect_class.__name__}" | ||
| withEffect.__doc__ = f""" | ||
| Adds a `.{effect_class.__name__}` and then draws the original Artist to |
There was a problem hiding this comment.
I've been struggling to understand what the with... classes are and what they are good for (path effect newbie here). Therefore I'm a bit picky on docs. I propose something like this (Please check ReST syntax and line length. This is a bit difficult in the github interface):
"""
A shortcut PathEffect for applying `.{effect_class.__name__}` and then
drawing the original Artist.
Examples
--------
With this class you can use ::
artist.set_path_effects([path_effects.with{effect_class.__name__}()])
as a shortcut for ::
artist.set_path_effects([path_effects.{effect_class.__name__}(),
path_effects.Normal()])
"""
There was a problem hiding this comment.
Taking for example the path effect proposed at #15458, using just path_effects=[TickedStroke(...)] would only draw the ticks, not the "original" path; using path_effects=[withTickedStroke(...)] draws both the original path and not the Stroke. Your suggestion is fine, adding it.
|
Bonus points if you add a link to https://matplotlib.org/3.1.1/tutorials/advanced/patheffects_guide.html in the module docstring. |
|
all suggestions integrated. |
| super().draw_path(renderer, gc, tpath, affine, rgbFace) | ||
| renderer.draw_path(gc, tpath, affine, rgbFace) | ||
|
|
||
| withEffect.__name__ = f"with{effect_class.__name__}" |
There was a problem hiding this comment.
So... if you have to do this big song and dance for the docs, is this change really worth it?
There was a problem hiding this comment.
It's more worth it if we keep adding new patheffects and repeat this code pattern again and again, e.g. #15458.
|
rebased |
PR Summary
could be used in #15458 as well.
PR Checklist