Support multi-version documentation on the website #1067

mdboom · 2012-08-10T16:05:52Z

Update index.html page.

This allows for multiple versions of the matplotlib documentation to
be made available.  The scheme is that the root
documentation (i.e. http://matplotlib.sf.net/) will always be the
latest stable version.  Other versions of the documentation will be
available in subdirectories off of the root (the latest stable version
is merely a symlink or redirect back to the root).  This is the same
convention used by "docs.python.org", as an aside.

The index.html page uses some JavaScript to load a little snippet of
HTML from "/versions.html" that lists the available versions.
"versions.html" is not part of this repository, but is part of the
matplotlib.github.com repository and is updated by hand whenever new
versions are added or removed from the archive.  This approach allows
all versions of the documentation to point to all other versions of
the documentation.  This JavaScript XMLHttpRequest magic doesn't
happen when the user is viewing static files on their local machine,
and this is a happy coincidence.

The perhaps controversial outcome of this change is that the summary
list of plotting commands is removed from the front page.  For one, we
want to steer people toward the version of the documentation that
corresponds to the version they are running.  Also, this was a
manually created list, and has become quite out of date over time.
Better, IMHO, to link to the pyplot documentation.

This freed up room to move much of the content that existed in the
sidebar to the main body, where I feel it's much less buried.  I plan
to add a lot more external resources and links, so having the room to
do this would be very helpful.

Adds a "Fork me on Github" banner.

This allows for multiple versions of the matplotlib documentation to be made available. The scheme is that the root documentation (i.e. http://matplotlib.sf.net/) will always be the latest stable version. Other versions of the documentation will be available in subdirectories off of the root (the latest stable version is merely a symlink or redirect back to the root). This is the same convention used by "docs.python.org", as an aside. The index.html page uses some JavaScript to load a little snippet of HTML from "/versions.html" that lists the available versions. "versions.html" is not part of this repository, but is part of the matplotlib.github.com repository and is updated by hand whenever new versions are added or removed from the archive. This approach allows all versions of the documentation to point to all other versions of the documentation. This JavaScript XMLHttpRequest magic doesn't happen when the user is viewing static files on their local machine, and this is a happy coincidence. The perhaps controversial outcome of this change is that the summary list of plotting commands is removed from the front page. For one, we want to steer people toward the version of the documentation that corresponds to the version they are running. Also, this was a manually created list, and has become quite out of date over time. Better, IMHO, to link to the pyplot documentation. This freed up room to move much of the content that existed in the sidebar to the main body, where I feel it's much less buried. I plan to add a lot more external resources and links, so having the room to do this would be very helpful. Adds a "Fork me on Github" banner.

mdboom · 2012-08-10T16:12:05Z

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

pelson · 2012-08-10T17:52:29Z

doc/_templates/index.html

-      </td>
+<p>There is an active developer community and a long list of people
+who have made significant <a href="{{ pathto('users/credits')
+}}">contributions</a>.</p>


The contributions page could probably do with a refresh too.

Agreed. I'll file a separate issue for that.

WeatherGod · 2012-08-10T20:14:16Z

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?

fperez · 2012-08-10T20:18:06Z

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 :)

mdboom · 2012-08-10T20:27:47Z

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.

fperez · 2012-08-10T22:21:01Z

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:

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
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.
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

mdboom · 2012-08-16T19:19:29Z

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.

efiring · 2012-08-17T07:13:02Z

doc/users/credits.rst

+Phil Elson
+  Fixed some deep-seated bugs in the transforms framework, and has
+  been laser-focused on improving polish throughout matplotlib,
+  tackling things that have been considered to large and daunting for


"to large" -> "too large"

efiring · 2012-08-17T07:29:14Z

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.

pelson · 2012-08-17T11:53:27Z

boilerplate.py

@@ -246,3 +246,12 @@ def %(name)s():
 for name in cmaps:
    print _fmtcmap%locals()

+print "# This function was autogenerated by boilerplate.py"


This is going to conflict with my changes to boilerplate which were put on master a month or so ago. Is there a reason for basing this against v1.1.x? Can this particular change be avoided to the v1.1.x line?

It might conflict and require a different solution on master -- but it needs to be here so the plotting command list can be autogenerated and moved off of the front page of the docs.

mdboom · 2012-08-17T12:23:26Z

@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.

pelson · 2012-08-17T12:24:39Z

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.

mdboom · 2012-08-17T12:32:10Z

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.

pelson · 2012-08-17T12:42:05Z

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

Support multi-version documentation on the website

pelson reviewed Aug 10, 2012
View reviewed changes

Gentler donation language.

3a1c832

mdboom mentioned this pull request Aug 10, 2012

Add stairstep plotting functionality #1068

Closed

mdboom added 2 commits August 16, 2012 15:09

Update credits page

b60f3ee

Add an autogenerated plotting command summary.

87f8df3

Fix small typo listing members to exclude

cd4c335

efiring reviewed Aug 17, 2012
View reviewed changes

pelson reviewed Aug 17, 2012
View reviewed changes

mdboom added 2 commits August 17, 2012 11:32

Add docstring to _setup_plot_info_docstrings

5a2d0a6

Update credits

fe2e95d

mdboom added a commit that referenced this pull request Aug 17, 2012

Merge pull request #1067 from mdboom/doc_multi_version

1057eed

Support multi-version documentation on the website

mdboom merged commit 1057eed into matplotlib:v1.1.x Aug 17, 2012

mdboom mentioned this pull request Aug 17, 2012

Doc multi version master #1100

Merged

mdboom deleted the doc_multi_version branch March 3, 2015 18:43

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Support multi-version documentation on the website #1067

Support multi-version documentation on the website #1067

mdboom commented Aug 10, 2012

mdboom commented Aug 10, 2012

pelson Aug 10, 2012

mdboom Aug 10, 2012

WeatherGod commented Aug 10, 2012

fperez commented Aug 10, 2012

mdboom commented Aug 10, 2012

fperez commented Aug 10, 2012

mdboom commented Aug 16, 2012

efiring Aug 17, 2012

efiring commented Aug 17, 2012

pelson Aug 17, 2012

mdboom Aug 17, 2012

mdboom commented Aug 17, 2012

pelson commented Aug 17, 2012

mdboom commented Aug 17, 2012

pelson commented Aug 17, 2012

Support multi-version documentation on the website #1067

Support multi-version documentation on the website #1067

Conversation

mdboom commented Aug 10, 2012

mdboom commented Aug 10, 2012

pelson Aug 10, 2012

Choose a reason for hiding this comment

mdboom Aug 10, 2012

Choose a reason for hiding this comment

WeatherGod commented Aug 10, 2012

fperez commented Aug 10, 2012

mdboom commented Aug 10, 2012

fperez commented Aug 10, 2012

mdboom commented Aug 16, 2012

efiring Aug 17, 2012

Choose a reason for hiding this comment

efiring commented Aug 17, 2012

pelson Aug 17, 2012

Choose a reason for hiding this comment

mdboom Aug 17, 2012

Choose a reason for hiding this comment

mdboom commented Aug 17, 2012

pelson commented Aug 17, 2012

mdboom commented Aug 17, 2012

pelson commented Aug 17, 2012