Repository navigation
[Doc]: .set_linestyle() tuple method is unclear #26784
Description
Documentation Link
Problem
I looked up a method for setting plot's spine line style to a custom dash and my lazy eye caught what I highlighted in yellow:
I tried this and naturally I got an error:
Only after googling some example and reading the doc very carefully I noticed the correct way to change the line style:
Suggested improvement
I think the doc should be re-written so it's more explicit:
Alternatively a dash tuple of the following form can be provided:
(offset, (off_ink, on_ink))
Where:
offset: definitionon_ink/off_ink: definition
Reacted by Ruth Comer
Activity
pawjast commentedon Sep 15, 2023
Also, the
lineobject has a methodset_dashes()and I wonder if it's a viable option to add a similar method to thespineobject.https://matplotlib.org/stable/gallery/lines_bars_and_markers/line_demo_dash_control.html
rcomer commentedon Sep 15, 2023
(offset, (on_ink, off_ink))I think this would not be quite right as it seems to imply only a length 2 on-off pattern, whereas any even number should work. The linestyles example explains things pretty well, so possibly a good way to improve here is to just link the example from the docstring?
oscargus commentedon Sep 15, 2023
There is a PR which deals with most of these things that hopefully will be merged for 3.9: #23056
(The discussions are really about what
get_linestyleandget_dashesshould return, as that is currently inconsistent between classes and unifying it will probably break some code somewhere.)For the original issue: yes, it is maybe unclear, but correct. Probably it can be clarified a bit further in the PR above, but it does link to the example @rcomer pointed out.
An additional challenge here is that
set_dashesonly takes theon-off-seq-part so it is not possible to changeoffsetlater.pawjast commentedon Sep 15, 2023
I haven't seen this page before. Thanks for sharing. And yes, I think having this page linked in the doc would help as well.
DOC: Clarify and unify set_linestyle
DOC: Clarify and unify set_linestyle
DOC: Clarify and unify set_linestyle (matplotlib#30855)