DOC: improve spines crosslinking #23316
Conversation
ba8d224 to
e071856
Compare
examples/spines/spines.py
Outdated
| @@ -8,6 +8,10 @@ | |||
| - normal Axes, with spines on all four sides; | |||
| - an Axes with spines only on the left and bottom; | |||
| - an Axes using custom bounds to limit the extent of the spine. | |||
|
|
|||
| Each `.axes.Axes` has a list of `~.Spine` objects, accessible | |||
There was a problem hiding this comment.
can this be formatted like the references section in https://matplotlib.org/stable/gallery/ticks/tick-formatters.html ?
There was a problem hiding this comment.
Not sure what you are after here?
There was a problem hiding this comment.
I think something like this makes it clearer what the api reference is than having it written out in the prose
but reading through again, this might be an in addition to rather than instead of suggestion (sorry!)
There was a problem hiding this comment.
Sure, that's a good suggestion. Newest version has that at the bottom now.
examples/spines/spines.py
Outdated
| @@ -8,6 +8,10 @@ | |||
| - normal Axes, with spines on all four sides; | |||
| - an Axes with spines only on the left and bottom; | |||
| - an Axes using custom bounds to limit the extent of the spine. | |||
|
|
|||
| Each `.axes.Axes` has a list of `~.Spine` objects, accessible | |||
There was a problem hiding this comment.
| Each `.axes.Axes` has a list of `~.Spine` objects, accessible | |
| Each `.axes.Axes` has a list of `.Spine` objects, accessible |
The only purpose of ~ is shortening link text to the last component of the given qualified name. So ~.Something is exactly the same as .Something and the latter is easier to read in the raw docstring.
There was a problem hiding this comment.
I mildly disagree - ~.Spine makes it clear to me that its relative to "home", eg the top level of the library, whereas .Spine makes me think its a submodule of the current module. I appreciate that's not how sphinx handles it, but when reading the raw docstring that's how I always think about it.
There was a problem hiding this comment.
Unfortunately, associating ~ with "home" is a false analogy. Coneceptually, ~ has nothing to do with the "path"/fully qualified name. It only affects the displayed text of the link. I advise against trying to use it for other purposes.
There was a problem hiding this comment.
Duh, sorry, you are right. I should have my coffee before reading GitHub.
examples/spines/spines.py
Outdated
| as ``ax.spines.left``, ``ax.spines.right``, ``ax.spines.bottom``, | ||
| and ``ax.spines.top``. |
There was a problem hiding this comment.
ax.spines.left and similar is only part of the spine accessor functionality. I suggest to link https://matplotlib.org/stable/api/spines_api.html#matplotlib.spines.Spines instead:
| as ``ax.spines.left``, ``ax.spines.right``, ``ax.spines.bottom``, | |
| and ``ax.spines.top``. | |
| via the container `ax.spines`. See `.Spines`. |
There was a problem hiding this comment.
I didn't do the See .Spines as we had just linked Spine in the sentence....
5821744 to
daa24b0
Compare
PR Summary
It is really hard to find the Spine class from the examples given, and it is hard to find the examples from the Spine class. This attempts to improve that...
PR Checklist
Tests and Styling
pytestpasses).flake8-docstringsand runflake8 --docstring-convention=all).Documentation
doc/users/next_whats_new/(follow instructions in README.rst there).doc/api/next_api_changes/(follow instructions in README.rst there).