Improve 'Writing ReST Pages' section on docs #20522
Comments
|
Most of above should be addressed by I've opened a separate dedicated issue #20534 for the headings, which we explicitly have to document because there is no universal convention. In "Writing ReST pages" we should only document formatting that is specific to Matplotlib. General "very common formatting" is covered by the links to Sphinx and docutils, we should not repeat that. AFAICS all other specific topics are already covered in "Writing ReST pages". But you are welcome to propose additional content that we may have overlooked. |
Yeah, I just added that we can also add a link to Sphinx side of the documentation.
I think the docs still miss a written guide/sample which allows a user to directly open the generated docs: In general, this issue's first paragraph I think would well enough be handled by #20534, the second and third paragraph still need to be addressed. (if I correctly read @timhoffm's comment that is 😅) |
|
Sorry, I mixed up the ticket numbers. Please read my comment above again, which now links correctly to the respectively mentioned content. |
Ah, no problem. I think the merged PR solves this issue entirely (except headings, for which we have a new issue). |
Uh oh!
There was an error while loading. Please reload this page.
Suggested Improvement
The documentation on reStructuredText: https://matplotlib.org/stable/devel/documenting_mpl.html#writing-rest-pages lacks some very common formatting like specifying the heading types (which is arbitrary in general, but might be worth putting down in docs for consistency throughout the documentation while writing/modifying one), links, etc.
The reST documentation links to: https://docutils.sourceforge.io/rst.html#reference-documentation, but it might also be worth pointing to a Sphinx side of it: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html (which seems a bit easier to read and navigate for someone new to writing docs).
I also didn't find anything which allows a user to directly open the generated docs:
make show. (even though it generates local HTML files, it might be worth adding this command to docs as well).Matplotlib version
import matplotlib; print(matplotlib.__version__)):The text was updated successfully, but these errors were encountered: