matplotlib.xkcd gallry misses xkcd call about matplotlib.github.com

[pelson]

I'm not sure whether I'd want to see the plt.xkcd() call in the examples. In for example http://matplotlib.org/xkcd/examples/shapes_and_collections/path_patch_demo.html . To produce the build @mdboom probably just set the necessary rcParameters that the xkcd function gives you for free rather than using the plt.xkcd() function itself - there are other RC parameters being set in all of the documentation builds which are not explicitly coded (figure size for instance) so it is not entirely unheard of.

@mdboom - have the final call on this one given it would be you who re-builds the XKCD version of the documentation anyway, though whilst I think @jakobgager is right to bring this up here, I'm comfortable not actually adding the necessary line.

Thanks to you both,

[jakobgager]

I'm fine without the explicit call, I would just add a note somewhere at the startpage or gallery page that all plots are created using e.g. a customized matplotlibrc.

[WeatherGod]

Since this feature is likely to bring many new users to matplotlib, they
may not understand enough of the underlying architecture to understand what
is happening with the plots. When they blindly try the examples and they
fail to produce the results they expect, that becomes a strike against us.

"Explicit is better than Implicit"

I am not exactly sure how to address this properly, but it certainly does
need to be addressed.

[mdboom]

Thanks for bringing this up. The xkcd version of the docs was really intended as a gimmick to show off the new feature, which, strictly speaking, is documented here:

http://matplotlib.org/1.3.0/api/pyplot_api.html?highlight=xkcd#matplotlib.pyplot.xkcd

As @pelson implied, all I did to generate that version of the docs was to set the plot_pre_code configuration variable to the plot directive so that it calls xkcd before each plot is made -- I didn't actually edit the files. Unfortunately, there's no easy way to do this all from rcParams -- it could be done, but it's many lines vs. the single line to call xkcd().

I guess we do need to address this, somehow. I think inserting code to the top of the examples will be tricky to do correctly. I'd sooner just add a banner to the top of the xkcd docs saying:

This is the xkcd version of the matplotlib documentation.  All plots were produced by turning on `xkcd mode` (link to the xkcd function documentation).  For the official docs go here (link to the official docs).

Does that sound like a reasonable solution?

[WeatherGod]

I think the banner might be the best way to go about this.

[jakobgager]

Sounds good for me too!
I'll keep this issue open until the banner is added, to have some reminder here.
Thx for your efforts and great work! 👍

[OceanWolf]

Ooh, just found this repo and curious as to how to how the updating of the docs works, (I currently work to get git set up for another project), but anyway, I see we have not yet closed this issue, has anyone started on this issue yet? How much of the code gets autogenerated? I.e. which files can I change, and which not?

[jenshnielsen]

@OceanWolf This issue is strictly about the xkcd version of the docs.

The docs at matplotlib.org/devdocs are automatically build from Travis. You can see how that is done by looking at the .travis.yaml file which contains everything needed to build the docs and push them back to a gppages branch at https://github.com/matplotlib/devdocs

[jenshnielsen]

That is to say everything in that repository and thus at matplotlib.org/devdocs is either coming directly from the main matplotlib repository.

[tacaswell]

Closing this as wont fix, the xkcd docs were a bit of a joke and are now way out of date.

[OceanWolf]

@jenshnielsen Sorry, I asked about two things at once, one my own curiosity, and the other about fixing this issue. Anyway, after quite a bit of poking, I now think I understand how it all works. Only the devdocs project has automation in it, the rest of the site gets built on our own boxes and pushed to this repo like any other push, (but without going through a PR).

Anyway, taking a look through the process I see two worrying things...

1. The latest release version of mpl keeps getting modified when we release a new version of mpl, meaning these files develop history unlike the version set version http://www.matplotlib.org/1.4.3/...
2. All of the code gets needlessly repeated. Fixing this will make resolve this bug easy.

To solve 2, normally this would get solved by using the server-side scripting, such as python (php, etcetera), but failing that we can go for client side scripting with javascript to dynamically paste in content surrounding the main page. This would mean the banner warning about 2.0 and everything else, menus etcetera can go in one file for easy updating.

To solve 1, normally I would go for a redirect, something like the following pseudo-code:

try:
  load_page(url)
except PageNotFoundException:
  latest_version = '1.4.3'  # perhaps some auto-detect logic based on looking at directories
  load_page(latest_version + url)  # if this fails it will fall-back to the 404 page

But alas we don't have access to any such server side code, not even anything akin to Apache's .htaccess, so the solution to this again comes from javascript. For the pages that we know will get duplicated (these shouldn't change between versions) we can use javascript to find and load the correct page into the browser.

Thoughts?

@tacaswell I assume you have a script on your machine to do all the auto-update logic, doesn't that update the xkcd stuff at the same time?

I think it would look nice to keep this joke running, if nothing else it serves to show what can get done with xkcd, and it provides an extra entry point to matplotlib, I find it some nice eye-candy :). Whatever stuff we find easier to fix with js we can do it that way.