re-organize gallery

[tacaswell]

@dpsanders Is the work from the sprint up someplace?

[msarahan]

Does this involve translating to IPython notebooks, or just reorganization? I vaguely remember the idea of translating all of the gallery into notebooks, and I'm interested in helping with that, especially for the image tutorial that I wrote so long ago. If I do a PR, where should I put the notebooks?

[efiring]

I don't think the gallery should be translated into notebooks at all. There should be a place for notebooks as tutorials, but I'm not sure what the best place would be.

[msarahan]

Yes, as I'm re-writing the image tutorial as a notebook, I'm recognizing the notebook's weaknesses in linking to other sections of the docs, relative to Sphinx. Translating is not the best idea.

I had an associate get hung up with the image tutorial because it was written before IPython notebooks, and many of the commands I used that made sense for interactive plotting don't make sense for the notebooks, where commands in one cell won't necessarily affect results of another cell further up.

I'll have a PR for a new Notebook-based image tutorial later today.

[tacaswell]

At scipy there was talk/consensus of turning at least a decent sub-set of the examples into ipython notebooks.

The education track at scipy was really pushing the potential of the notebooks for teaching. At least for tutorial-type examples I think we should embrace them as well.

[efiring]

A problem is that then they are not directly visible and usable as text. What's the advantage of replacing them with notebooks? I use notebooks for tutorials (e.g. http://currents.soest.hawaii.edu/ocn760_4/python_tutorial.html), but our examples are different. I think there is still a place for simple scripts--and this is it. Notebooks are good for some things, but not for everything.

[efiring]

See http://python.6.x6.nabble.com/Using-IPython-notebooks-to-teach-Python-tt5068743.html (message by Greg Wilson).

[msarahan]

IMHO, notebooks are great for any example that is more than a trivial number of commands. The whole cell interface makes it really nice and easy to tweak things and see how those tweaks affect things. It more completely separates stages of an example, and lets each stage be tweaked. If there's more than 2-3 steps in any given example, a notebook might be nice.

The downsides of the notebook are as you (through Greg) point out: no text diffing (yet?), and yet another thing to learn, though with the static nbviewer, it's pretty much the same thing as any static webpage example (minus the source diff for reviewing edits). I also find it less easy to flip between links in the same way as a webpage - not that it should be any harder, since it is a webpage, but it just seems to be in practice. Maybe something mental. I tend to alt-tab between applications, and alt-tabbing in a browser obviously doesn't do the same thing I'm mentally reaching for, in terms of context switching. Any notebook will also be more prone to link rot in the internal doc links, but that's less of a concern with a mature project like Matplotlib.

Just my 2 cents... PR's for both a revised image tutorial, and a notebook-based image tutorial should be posted.

[lenriqc]

@tacaswell Sorry for the delay in replying. It's here: https://github.com/dpsanders/matplotlib/compare/gallery_reorg

I was working on it, but ran into a problem that I posted to the mailing list: there seems to be some strange chain of inclusions of files that means that the files I moved no longer are found when making some documentation or other, legend_demo if I remember correctly. But I never worked out which step was going wrong.

If you can have a look and fix this, I can carry on with the work. (Also got caught up with the start of term of course...)

Halfway through the process I was shocked to see the backend_driver.py file, which has everything listed by hand. This makes the process infinitely more nasty. Is there anyway round that? In my opinion, as much as possible should be automated.

In fact, I made a neat script, that I included in the repo, to move the files to the right directory and fix up links from the reST documentation in the correct way, but fixing backend_driver.py will be much more painful...

[tacaswell]

huh, didn't know that file existed...

Link to the mailing list post? I don't recall seeing it go by.

[dpsanders]

http://matplotlib.1069221.n5.nabble.com/How-to-find-references-to-examples-td43659.html

I don't remember seeing it come up in a posting...

Yes, that file is a nightmare...
I'm not even sure what it is for.
But when @tonysyu did his gallery example cleanup, he also had to touch that file.

[WeatherGod]

backend_driver.py is an old smoketest script. It still has its uses, but
why is it being picked up by sphinx?

On Mon, Aug 25, 2014 at 1:44 PM, David Sanders notifications@github.com
wrote:

http://matplotlib.1069221.n5.nabble.com/How-to-find-references-to-examples-td43659.html

I don't remember seeing it come up in a posting...

Yes, that file is a nightmare...
I'm not even sure what it is for.
But when @tonysyu https://github.com/tonysyu did his gallery example
cleanup, he also had to touch that file.

—
Reply to this email directly or view it on GitHub
#3377 (comment)
.

[efiring]

backend_driver.py has been very useful because it quite extensively tests several backends, both for functionality and for speed. It used to be the only major test jig for mpl. It has fallen out of use now that we have all the nosetests, but it has some functionality that the nosetests lack.

[efiring]

To elaborate on backend_driver.py: like the rest of mpl, it grew organically, so it is not what it would be if one were starting now to design it from scratch. The reason it uses a list of examples is that not all of the examples are suitable for automated testing. Some require interaction. If we were designing the example set and backend_driver now, we might use a standardized system of comment lines at the top of each script to indicate whether it should be in the gallery, whether it should be run by backend_driver, and if so, whether it is general or whether it is restricted to particular backends. Then backend_driver would generate its test list by scanning all the example scripts.

[petehuang]

This issue was posted following a sprint session in 2014. Is this addressed by the work at #7206?

[anntzer]

I think this is covered by #7206 indeed.