GeezerVison

I put this up on http://matplotlib.github.com/ so you can preview the changes.

I am not a fan of removing that list of functions. If it gets removed there, then it needs to be somewhere else. The problem isn't with the list itself, it is with maintenance of that list. Surely, we can come up with a sphinx-y way to generate a condensed table of methods from the pyplot.py api?

Glad to see you moving in this direction. I've never liked the fact that there's no way to get to mpl's old docs easily, and I actually think that having the website build be part of the project itself is unnecessary and makes things harder than they need to be. I'd kindly suggest that you guys copy the ipython approach, where we have a separate website repo that is lightweight and minimal, and is even managed by a separate team from the main repo team.

That lets people improve the website without having to dig into the entire codebase, and lets you give commit rights to just the website to contributors who may not necessarily be ready to commit into the main repo.

Just a suggestion :)

The problem with having the list on the front page is that it will go to version-specific documentation of those functions. One of the reasons for this patch is to have a landing page that is non-version-specific and to encourage people to select the version of the documentation that matches their version of matplotlib. But I'm not opposed to sticking the list somewhere else in the tree, and, yes, have it be auto-generated.

@fperez: I had considered moving the landing page to the website repository, but didn't want to change the structure of local docs -- as distributed by Debian for example. That does get me thinking though -- the index.html in the Sphinx docs could certainly be a stripped down version of the landing page that is only ever used in local copies of the docs.

On Fri, Aug 10, 2012 at 1:27 PM, Michael Droettboom <
[email protected]> wrote:

@fperez https://github.com/fperez: I had considered moving the landing
page to the website repository, but didn't want to change the structure of
local docs -- as distributed by Debian for example. That does get me
thinking though -- the index.html in the Sphinx docs could certainly be a
stripped down version of the landing page that is only ever used in local
copies of the docs.

I think in fact it makes more sense, when you think of distributions, not
to ship a website along with a local project. What a distribution wants to
ship is the build of the docs for the specific version of the project they
ship, while a project wants to have a main website, that includes links to
the documentation for all versions. This is how we do it:

1. ipython.org: main site, with sources at
   https://github.com/ipython/ipython-website and built site with gh-pages
   branch at: https://github.com/ipython/ipython.github.com
2. http://ipython.org/documentation.html: landing page for documentation,
   kept as part of the main site above. It summarizes everything and contains
   links for all the doc versions.
3. https://github.com/ipython/ipython-doc: the repo that actually contains
   the builds of all the docs using a gh-pages branch. This is what the pabe
   in Svn2git #2 above points to.

The docs are trivially built for each version at release time, and also
whenever an update is warranted, thanks to a simple target in our makefile
and one little script:

https://github.com/ipython/ipython/blob/master/docs/Makefile
https://github.com/ipython/ipython/blob/master/docs/gh-pages.py

HTH,

f

I'm convinced that people are using the plotting command summary, so I've added a commit that generates a plotting command summary automatically. It is not on the front page, because given multi-version documentation, it doesn't make much sense to link directly into a particular version of the docs.

This had quite a few tentacles into other things, the I would like to address fully, but instead chose to do the minimum that will get this done in time for the freeze. For example, sphinx' autosummary directive doesn't alone list all of the members of a given module, so you have to have a way to create the list of commands. pyplot.py had a get_plot_commands function, but it was a hard coded list and rather incomplete. pyplot.py also has a plotting docstring-only function that lists plotting commands -- also hardcoded and out-of-date. And then there's the list in the docs. All three had different subsets of the plotting commands in pyplot.py. So I chose to address all three of these problems at once and make the website based on the plotting docstring, which in turn is generated based on the result of get_plot_commands. The good way to do this would have been to revamp the boilerplate mechanism a little bit, but I'm not sure that's a change to fit in before the freeze. All that long explanation is just to cut off at the chase any "why didn't you also address 'x' while you were in there" sorts of comments. Believe me, this was a hard one to keep reasonably-scoped.

Since you are updating the credits.rst, I think it is important to add Ian Thomas, who contributed the tricontour and tripcolor capabilities, and Michiel de Hoon, who wrote the macosx backend. (Ian also fixed the masking bug in the regular contour code, which had completely defeated me.)

Also, I am surprised to see this as a merge to v1.1.x; it seems more appropriate for master. No harm in putting it in v1.1.x, though, and then merging to master.

In any case I would be happy to see you go ahead and merge it.

@efiring: Just boneheaded oversight on the credits.rst additions. I will add that. This is merged into 1.1.x because the real impetus for this change is to allow for having multiple versions of the documentation available online -- without breaking too many existing links into the documentation that may exist elsewhere. This involves changing the landing page so it can point to other versions of the documentation and removing the master plot command list from the front page since it's confusing to present that level of detail without making it clear what version of the documentation they would be getting. For the 1.2 release, I'd like to have the 1.1 and 1.2 documentation available simultaneously.

I think I agree with @efiring.

This is a massive improvement, but I'm not sure about putting it against v1.1.x. These concerns are down to two main issues:

• merging to v1.1.x and then over to master will cause some conflicts (boilerplate has been reworked since they diverged)
• there is no real benefit to applying it to v1.1.x. I don't think it would be appropriate to release this as "the documentation for v1.1.1", as docstrings will be slightly different when comparing online vs inline.

Other than my comments, I am happy with these changes. Thanks @mdboom.

I hope I've explained why this goes on 1.1.x. If we don't make this change, then it's not made clear that the user is viewing the 1.1.x documentation and be provided with links to the other version. Yes -- some of the docstrings will be different -- but not in any substantive way. We ameliorate that, we could do a 1.1.2 release.

And yes, merging into master will be non-straightforward, but that's fine in the end.

Ok. Good answers. You have satisfied me on the need to put it against 1.1.x. +1