Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Already on GitHub? Sign in to your account

Support multi-version documentation on the website #1067

Merged
merged 7 commits into from Aug 17, 2012

Conversation

Projects
None yet
5 participants
Owner

mdboom commented Aug 10, 2012

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.
@mdboom mdboom 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.
9745bdd
Owner

mdboom commented Aug 10, 2012

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

Perhaps more subtle would be:
Please consider donating ...

Also, is it possible/desirable to provide a page which details the use of the donations? hosting/domain/scipy beers etc.?

Owner

mdboom replied Aug 10, 2012

Agreed that that is improved language.

I'll file an issue for adding a page about donations later -- all that stuff is in a bit of flux right now.

I have been experimenting with providing support on stackoverflow and have found it really nice. Would we want to encourage that over the user mailing list?

Owner

mdboom replied Aug 10, 2012

That's a great idea. I don't know if we necessarily want to encourage one over the other at this point, but it would probably be very helpful to link to the stackoverflow entries tagged with "matplotlib":

http://stackoverflow.com/questions/tagged/matplotlib

I'm glad the pyplot functions are removed from the homepage, but maybe a link to the pyplot docs would be helpful.

Owner

mdboom replied Aug 10, 2012

It's linked as "list of plotting commands" under the Documentation section. Perhaps it should be elsewhere?

@pelson pelson commented on the diff Aug 10, 2012

doc/_templates/index.html
- <td align="left">
- set the default colormap to spectral
- </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>
@pelson

pelson Aug 10, 2012

Member

The contributions page could probably do with a refresh too.

@mdboom

mdboom Aug 10, 2012

Owner

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

@pelson pelson and 1 other commented on an outdated diff Aug 10, 2012

doc/_templates/index.html
<p>matplotlib tries to make easy things easy and hard things possible.
You can generate plots, histograms, power spectra, bar charts,
errorcharts, scatterplots, etc, with just a few lines of code.
For a sampling, see the <a href="{{ pathto('users/screenshots') }}">screenshots</a>, <a href="{{ pathto('gallery') }}">thumbnail</a> gallery, and
-<a href="examples/index.html">examples</a> directory</p>
-
- <p align="center"><a href="{{ pathto('users/screenshots') }}"><img align="middle"
- src="{{ pathto('_static/logo_sidebar_horiz.png', 1) }}" border="0"
- alt="screenshots"/></a></p>
-
+ <a href="examples/index.html">examples</a> directory</p>
<p>For example, using "ipython -pylab" to provide an interactive
@pelson

pelson Aug 10, 2012

Member

This example always bothers me. Could we not change it to use the pyplot interface and leave it to simply mention that this can be done in 2 lines with ipython?

@WeatherGod

WeatherGod Aug 10, 2012

Member

Actually, I think that the most simple example possible with matplotlib should be front-n-center

However, isn't "ipython -pylab" deprecated for "ipython --pylab"? Of course, we would have to consider when they starting allowing the double-dash.

@pelson pelson commented on the diff Aug 10, 2012

doc/_templates/index.html
- <td align="left">
- set the default colormap to jet
- </td>
+ Matplotlib 1.1.1 is available for
+<a href="https://sourceforge.net/projects/matplotlib/files/matplotlib/matplotlib-1.1.1/">download</a>.
@pelson

pelson Aug 10, 2012

Member

Can we use the github downloads section instead?

@mdboom

mdboom Aug 10, 2012

Owner

I think that's something we'll move to for the next release -- perhaps putting duplicates of the 1.1.1 release there as well at the same time.

Member

WeatherGod commented Aug 10, 2012

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?

Member

fperez commented Aug 10, 2012

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

Owner

mdboom commented Aug 10, 2012

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.

Member

fperez commented Aug 10, 2012

On Fri, Aug 10, 2012 at 1:27 PM, Michael Droettboom <
notifications@github.com> 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 #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

Owner

mdboom commented Aug 16, 2012

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 efiring commented on the diff Aug 17, 2012

doc/users/credits.rst
+ faster, lighter and meaner. Listen to his podcast.
+
+Tony Yu
+ Has been involved in matplotlib since the early days, and recently
+ has contributed stream plotting among many other improvements. He
+ is the author of mpltools.
+
+Benjamin Root
+ Has significantly improved the capabilities of the 3D plotting. He
+ has improved matplotlib's documentation and code quality throughout,
+ and does invaluable triaging of pull requests and bugs.
+
+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
@efiring

efiring Aug 17, 2012

Owner

"to large" -> "too large"

Owner

efiring commented Aug 17, 2012

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 pelson commented on the diff Aug 17, 2012

boilerplate.py
@@ -246,3 +246,12 @@ def %(name)s():
for name in cmaps:
print _fmtcmap%locals()
+print "# This function was autogenerated by boilerplate.py"
@pelson

pelson Aug 17, 2012

Member

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?

@mdboom

mdboom Aug 17, 2012

Owner

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.

@pelson pelson commented on the diff Aug 17, 2012

doc/_templates/index.html
@@ -17,23 +52,17 @@
web application servers, and six graphical user
interface toolkits.</p>
-
-
-
-
+ <p align="center"><a href="{{ pathto('users/screenshots') }}"><img align="middle"
+ src="{{ pathto('_static/logo_sidebar_horiz.png', 1) }}" border="0"
@pelson

pelson Aug 17, 2012

Member

The filename is definitely out of date. This image represents the screen-shots on the front page. Perhaps call it screenshot_button.png (the exact name I don't really mind).

@mdboom

mdboom Aug 17, 2012

Owner

Ah, ok. Good point.

@pelson pelson commented on the diff Aug 17, 2012

lib/matplotlib/pyplot.py
@@ -1677,8 +1704,56 @@ def colormaps():
In interactive mode, this will update the colormap allowing you to
see which one works best for your data.
"""
- pass
-
+ return _colormaps()
+
+
+def _setup_pyplot_info_docstrings():
@pelson

pelson Aug 17, 2012

Member

I know its not a public interface, but a docstring would be nice.

@pelson pelson commented on the diff Aug 17, 2012

lib/matplotlib/pyplot.py
+ import re
+
+ def pad(s, l):
+ """Pad string *s* to length *l*."""
+ if l < len(s):
+ return s[:l]
+ return s + ' ' * (l - len(s))
+
+ commands = get_plot_commands()
+
+ first_sentence = re.compile("(?:\s*).+?\.(?:\s+|$)", flags=re.DOTALL)
+
+ # Collect the first sentence of the docstring for all of the
+ # plotting commands.
+ rows = []
+ max_name = 0
@pelson

pelson Aug 17, 2012

Member

Did you know there is a markup for rst tables which means you don't need to do this? See http://docutils.sourceforge.net/docs/ref/rst/directives.html#id2

.. csv-table:: Frozen Delights!
   :header: "Treat", "Quantity", "Description"
   :widths: 15, 10, 30

   "Albatross", 2.99, "On a stick!"
   "Crunchy Frog", 1.49, "If we took the bones out, it wouldn't be
   crunchy, now would it?"
   "Gannet Ripple", 1.99, "On a stick!"
@mdboom

mdboom Aug 17, 2012

Owner

Sure. But I want this docstring to be human readable as well.

@pelson

pelson Aug 17, 2012

Member

Ok. Good point.

P.S. If this were against master, I would consider auto generating the table in boilerplate.py rather than doing it on import of pyplot.

Owner

mdboom commented Aug 17, 2012

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

Member

pelson commented Aug 17, 2012

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.

Owner

mdboom commented Aug 17, 2012

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.

Member

pelson commented Aug 17, 2012

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

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

@mdboom mdboom Merge pull request #1067 from mdboom/doc_multi_version
Support multi-version documentation on the website
1057eed

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

@mdboom mdboom referenced this pull request Aug 17, 2012

Merged

Doc multi version master #1100

@mdboom mdboom deleted the mdboom:doc_multi_version branch Mar 3, 2015

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment