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

Doc multi version master #1100

Merged
merged 16 commits into from Aug 19, 2012

Conversation

Projects
None yet
2 participants
Owner

mdboom commented Aug 17, 2012

This is #1067 rebased against master. There shouldn't be too much to vet here, except for @pelson's benefit to see how the changes to boilerplate.py were handled.

There was no need to generate a colormap list in this case, since master already has a correct and autogenerated list of colormaps thanks to the work by @endolith.

It was not possible to generate the plotting docstring in boilerplate.py, since boilerplate.py doesn't know about any of the hard-coded functions in pyplot.py (gca, gcf etc.) -- ideally at some point all that stuff should probably be cleaned up, but this is working for now.

mdboom added some commits Aug 3, 2012

@mdboom mdboom Reinstate the manual reference counting as discovered in #1054. ca678a4
@mdboom mdboom Merge pull request #1054 from mdboom/doc_build_fail
 stix_fonts_demo.py fails with bad refcount
8089e04
@mdboom mdboom Fix gallery links (#1024) 64e64f6
@mdboom mdboom Merge pull request #1024 from mdboom/fix-gallery
broken links in the gallery
ff883a6
@mdboom mdboom Fix pythonxy link c9c108e
@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

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?

Owner

mdboom commented Aug 17, 2012

Note also: There are a ton of warnings and errors in the master doc build right now. I will create another pull request for that.

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

@mdboom mdboom Merge pull request #1100 from mdboom/doc_multi_version_master
Doc multi version master
b3f6783

@mdboom mdboom merged commit b3f6783 into matplotlib:master Aug 19, 2012

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

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