Uh oh!
There was an error while loading.Please reload this page.
- Notifications
You must be signed in to change notification settings - Fork7.9k
DOC: Minor enhancements to documenting_mpl#9872
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.
Already on GitHub?Sign in to your account
Uh oh!
There was an error while loading.Please reload this page.
Conversation
| 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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
😮 I didn't know this!
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
often not = unless there's a collision
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
Addedunless 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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
may be worth explaining briefly why single backquotes doesn't work (arguments don't have an entry)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
will (unsuccessfully) attempt to etc.
8a75109 tobf36c4fCompareRebased 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.... |
Uh oh!
There was an error while loading.Please reload this page.
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