DOC: Minor enhancements to documenting_mpl #9872
Conversation
d4f97ef to
216f042
Compare
| objects that can be referenced (in this case for Numpy):: | ||
| returns a link to the documentation of | ||
| `~matplotlib.collections.LineCollection`. If we want the full path of the | ||
| class to be shown then we omit the tilde: |
There was a problem hiding this comment.
Yeah, @anntzer explained it all to me (somewhere). Its also nicely explained at the very bottom of this very long section in the sphinx docs:
http://www.sphinx-doc.org/en/stable/domains.html#the-python-domain
Could the discoverability of this be better? Probably!
doc/devel/documenting_mpl.rst
Outdated
| `matplotlib.collections.LineCollection` | ||
|
|
||
| to get `matplotlib.collections.LineCollection`. Its often not | ||
| necessary to fully specify the class hierarchy: |
There was a problem hiding this comment.
often not = unless there's a collision
There was a problem hiding this comment.
Added unless there is a namespace collision between two packages
| documentation is built. | ||
|
|
||
| Similarly, the contents of :file:`docs/gallery` and :file:`docs/tutorials` are | ||
| generated by the `Sphinx Gallery`_ from the sources in :file:`examples` and |
There was a problem hiding this comment.
not directly related but I think the "examples" folder should be renamed "gallery" or the "gallery" folder on the website should be renamed "examples"...
There was a problem hiding this comment.
Yeah I agree. Its very confusing. I prefer "examples".
doc/devel/documenting_mpl.rst
Outdated
| `numpy.mean` | ||
|
|
||
| will return this link: `numpy.mean`. This works for Python, Numpy, Scipy, | ||
| and Pandas. Sometimes it is tricky to get external Sphinx linking to work; to |
There was a problem hiding this comment.
note that the list of packages for which it works is in conf.py
|
|
||
| python -m sphinx.ext.intersphinx 'https://docs.scipy.org/doc/numpy/objects.inv' | ||
|
|
||
|
|
||
| Function arguments | ||
| ------------------ | ||
| ~~~~~~~~~~~~~~~~~~ | ||
|
|
There was a problem hiding this comment.
may be worth explaining briefly why single backquotes doesn't work (arguments don't have an entry)
There was a problem hiding this comment.
Changed to:
Do not describe `argument` like this. As per the previous section,
this syntax will attempt to resolve the argument as a link to an object in the
library.There was a problem hiding this comment.
will (unsuccessfully) attempt to etc.
8a75109 to
bf36c4f
Compare
bf36c4f to
8dee7a3
Compare
|
Rebased off master, so it includes changes in #9875 |
|
#9884 includes these changes and more, so closing this in favour... |
|
Can re-open if #9884 doesn't go anywhere.... |
PR Summary
This is a follow-on from #9805
Includes anntzer's suggested changes for the artist introspection phrase...
Includes my suggestions for a bit more of an overview at the beginning of what comes from where in the build process.
I think this document could still be improved, but that can be longer-term. I thought I'd submit these changes while they are on everyone's minds... See outline at #9876
PR Checklist