Initial rework of gen_gallery.py #714

Merged
merged 1 commit into from Sep 5, 2012

Conversation

Projects
None yet
4 participants
Member

WeatherGod commented Feb 23, 2012

  • Creates a toc at the top of the gallery page
  • entries are created by a list of sub-directories
  • examples from each sub-dir is sectioned

After this change, we could then focus on re-organizing the examples directory. Comments welcome!

@WeatherGod WeatherGod Initial rework of gen_gallery.py
* Creates a toc at the top of the gallery page
* entries are created by a list of sub-directories
* examples from each sub-dir is sectioned
1a82ebe

@tonysyu tonysyu commented on the diff Feb 23, 2012

doc/sphinxext/gen_gallery.py
thumbnails = {}
+ rows = []
+ toc_rows = []
+
+ link_template = """\
+ <a href="%s"><img src="%s" border="0" alt="%s"/></a>
+ """
+
+ header_template = """<div class="section" id="%s">\
@tonysyu

tonysyu Feb 23, 2012

Contributor

Maybe the div class could be "gallery" so that someone can change the style for the gallery later. The image gallery is different than most pages (mostly images instead of text) and may require different styling (for example, underline the heading, extra spacing between sections, etc.)

@tonysyu tonysyu commented on the diff Feb 23, 2012

doc/sphinxext/gen_gallery.py
thumbnails = {}
+ rows = []
@tonysyu

tonysyu Feb 23, 2012

Contributor

Maybe rename to body_rows or gallery_rows or data_rows (but this may be confusing b/c it has no relation to the existing data variable)?

@tonysyu tonysyu commented on the diff Feb 23, 2012

doc/sphinxext/gen_gallery.py
- if thumbfile is not None:
- link = 'examples/%s/%s.html'%(subdir, basename)
- rows.append(link_template%(link, thumbfile, basename))
+
+ for (subdir, basename, thumbfile) in data:
+ if thumbfile is not None:
+ link = 'examples/%s/%s.html'%(subdir, basename)
+ rows.append(link_template%(link, thumbfile, basename))
+
+ if len(data) == 0:
+ warnings.warn("No thumbnails were found in %s" % subdir)
+
+ # Close out the <div> opened up at the top of this loop
+ rows.append("</div>")
+
+ content = template % ('\n'.join(toc_rows),
@tonysyu

tonysyu Feb 23, 2012

Contributor

Maybe rename to gallery_template to contrast it with the new templates you added?

Contributor

tonysyu commented Feb 23, 2012

Looks good! I'm looking forward to doing some gallery sorting (and clean-up) in the near future.

Collaborator

jdh2358 commented Feb 26, 2012

I have a couple of very general comments. The first is that this is a definite improvement over what we have currently and I have no problem pushing something like this to the site. How would this work with subdirs, like pylab_examples/histograms?

Beyond that, I am not sure that a directory based approach is the right one. Under the "flat is better than nested' philosophy, if we break the examples into lots of dirs and subdirs, it can make it harder to find what you are looking for using file system navigation and grepping. Also, it implies a one example one concept mapping that is likely not right for many examples. One could use links to avoid this, by linking to the same example from multiple conceptual directories, but I am not sure how well this will work across platforms.

An alternative is to support some metadata tagging in the example file itself. Something simple at the top or bottom of the example like:

#_gallery_
# topic: images, colormapping

the parser would detect a comment line starting with gallery and then parse all the subsequent comment lines before a blank to extract key -> value entries for a dictionary. This would enable us to tag a single example with multiple topics, and allow us to support other metadata to enrich the gallery. Eg, we might want to have some links to the API and other docs with some simple rest markup that gets rendered, like:

#_gallery_
# topic: images, colormapping
# seealso: :func:`~matplotlib.pyplot.imshow`, :ref:`image-tutorial`, :ref:`pylab_examples-axes_demo`

I imagine the gallery would be two tiered: at the top would be any examples that are "curated" ie, already tagged with metadata. In the process of tagging them, we would clean them and comment them and implement the recommended coding practices. After all the curated examples that have topics would come "the rest" which would basically be what you have already have. All the non-curated examples, organized by directory. That way at least the stuff people see first will have been cleaned.

I will be sprinting Friday night at pydata and may try to rope some contributors in. I'd be interested in working on this if you and others want to join.

Member

WeatherGod commented Feb 27, 2012

No plans for recursive subdir support. That would just make things complicated for all the reasons you stated.

The tagging idea you have is actually what I would like to implement, but I would like to try doing it within the spinx framework. I am thinking about an extension that would generate a gallery based on the tags (and maybe the examples page?) But, even further, I would like to see if a tagging approach can be used to improve the axes.py api page.

As for Friday, I will have to see how much progress I make on my current responsibilities.

Owner

mdboom commented Jun 1, 2012

What's the status here? This would be awfully nice to have.

Member

WeatherGod commented Jun 7, 2012

@jdh2358 and I fleshed out a very basic sphinx tagging extension that will likely be used instead. If we want to release the next version before the SciPy conference, then we could go ahead with this idea for now and undo it later when we implement tagging. It is unlikely I will get back to this before the SciPy sprints.

Contributor

tonysyu commented Jun 27, 2012

This is probably a little late, but I just want to voice my support of this PR regardless of whether or not tagging is added.

Tagged examples will be a big win for users with specific goals; but for many users, the plot gallery will remain the entry point to plot examples and sections could really help users navigate the gallery. The current example directories won't be terribly useful to users, but some new directories (displayed as sections) in the gallery would help. For example:

  • basic (bare-minimum code to use core plotting functions)
  • advanced (plots with tweaks to make them publication-quality)
  • specialty (e.g., sankey, radar, tornado)
  • reference (e.g., 'show_colormaps.py', 'artist_demo.py', 'annotation_demo2.py', 'anatomy of a matplotlib plot' mentioned in #524)
  • separate sections for toolboxes (already exists)

These would all be top-level sections with no subsections (to address concerns about nested directories).

I think these sections would also help guide a cleanup of the examples: Initially, all the current examples would remain and be listed under their current directories. Over time, these examples could be cleaned up and then moved into one of the above categories. The old examples could then either be deleted or shoved in some dark corner for posterity. Sure, we could do this cleanup without the section headings, but with sections, it becomes obvious which examples have been updated in the gallery.

Member

WeatherGod commented Aug 21, 2012

Did we still want to go ahead with this plan as a stop-gap? I have been working on a "codex-tag" sphinx extension, but haven't gotten it fully working yet. Plus we still lack the actual set of tags. There was somebody at the scipy sprints who was working on a list of tags to use, but he never emailed them to me, unfortunately.

Owner

mdboom commented Aug 21, 2012

I'd like to see this go ahead, even without tags. If you think there's a reasonable time for this before rc1 (in three weeks), please go ahead and add this to the 1.2.x milestone.

Member

WeatherGod commented Sep 4, 2012

Tags aren't going to happen in time. Hurricane season sucked too much of my free time and I really got to get back to working on my dissertation.

Owner

mdboom commented Sep 4, 2012

Ok -- just for my clarification: you think this is ok to merge even without the tags?

Member

WeatherGod commented Sep 4, 2012

Yes, this is the stop-gap solution until we have a proper tag solution. Essentially, the folders for the examples serves as the proxy for tags.

@mdboom mdboom added a commit that referenced this pull request Sep 5, 2012

@mdboom mdboom Merge pull request #714 from WeatherGod/docs/gallery_remake
Initial rework of gen_gallery.py
fc07958

@mdboom mdboom merged commit fc07958 into matplotlib:master Sep 5, 2012

WeatherGod deleted the WeatherGod:docs/gallery_remake branch Jul 23, 2014

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