Each pyplot function deserves its own page

[brandon-rhodes]

I find that I spend most of my time on this page, looking up options to remember how they work or to figure out why my plot does not look like I expect:

http://matplotlib.org/api/pyplot_api.html

But it is a very difficult page to navigate, without any shortcuts to jump to the particular function that I need to read about. Is there any way that the page could be split up to document one function per HTML page, with perhaps a small block of quick-links at the top to make it easy for people to jump among the (smaller) HTML pages that then would result?

[pelson]

Just checking, are you aware of: http://matplotlib.org/api/pyplot_summary.html ?

[brandon-rhodes]

Thanks for the link, @pelson, I should not have omitted it from the issue! Yes, I am aware of that page. But a Google search for most matplotlib features seems to land me on the main API page where such features are mentioned, and there is no obvious way to “back up” to the summary page so that I can then re-enter the API page down where I need to.

I should also, I realize, go ahead and ask a question that I suppose is implicit in this issue but that I had not formulated: What is the purpose or advantage of having so much API content on a single page? Is there any, or was it just the Sphinx path of least resistance?

I am giving a Sphinx tutorial next week at PyCon, and, it occurs to me, the question of how much API to put on one page will probably come up because of the recent blog post dinging Python for putting all built-in type documentation on a single page that is onerous to navigate (which I must admit that I agree with, it costs me time every week!):

http://joepie91.wordpress.com/2013/02/19/the-python-documentation-is-bad-and-you-should-feel-bad/

[WeatherGod]

On Mon, Mar 4, 2013 at 4:05 PM, Brandon Rhodes notifications@github.comwrote:

Thanks for the link, @pelson https://github.com/pelson, I should not
have omitted it from the issue! Yes, I am aware of that page. But a Google
search for most matplotlib features seems to land me on the main API page
where such features are mentioned, and there is no obvious way to “back up”
to the summary page so that I can then re-enter the API page down where I
need to.

I should also, I realize, go ahead and ask a question that I suppose is
implicit in this issue but that I had not formulated: What is the purpose
or advantage of having so much API content on a single page? Is there any,
or was it just the Sphinx path of least resistance?

I think it was a sphinx path of least resistance. Personally, I find
myself typing '/' and then the name of the function in firefox often, and
that usually gets me to where I need, but not always. By the way, are you
aware of the MEP10 work that is going on to improve the documentation.
Input from sphinx gurus would always be welcomed!

Ben Root

[mdboom]

I just want to secondly point out @NelleV 's Mep10 work which adds summary tables to these long pages. Nelle has a build of this work available at http://cbio.ensmp.fr/~nvaroquaux/matplotlib/doc/

Feedback at this stage would be great and also for those inclined to help out, since this is a lot of work to modernize everything.

[mdboom]

I should also add that as a reasonably early adopter of sphinx, matplotlib's usage predates automodsumm, numpydoc and other really nice extensions. mep10 is all about moving to that, and the mep itself might be educational in explaining how sphinx has evolved over time etc...

[tacaswell]

This has not had action on almost a year, closing.