<br><br><div class="gmail_quote">On Thu, Feb 23, 2012 at 6:18 PM, Fernando Perez <span dir="ltr">&lt;<a href="mailto:fperez.net@gmail.com" target="_blank">fperez.net@gmail.com</a>&gt;</span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">


<div><br>
</div>Ahh, I can breathe better already :)  Speaking of the gallery (this is<br>
getting OT for ipython), I think it&#39;s in serious need of a cleanup.  I<br>
appreciate today&#39;s PR on organizing it by sections, but the real issue<br>
is that over the years, the gallery has accrued a lot of scripts<br>
without any comments or explanations of purpose, deprecated APIs, etc.<br>
 I wonder if you could spur a &#39;gallery cleanup&#39; project, encouraging<br>
users to submit pull requests that remove duplicate/similar examples,<br>
document better the ones left, etc.  While there&#39;s a lot of good stuff<br>
there and I continue to point people to it, there really is also a<br>
massive amount of weed growth that is starting to be annoying in<br>
practice.<br>
<br>
But the cleanup job is easy, can be done by non-experts (and is hence<br>
a great one for new developers to start contributing) and would be<br>
very beneficial to the project at large.<br>
<div><br></div></blockquote><div><br></div><div>I will get involved in that thread.  I agree that something more curated would be preferable.  I&#39;m imagining some sort of metadata one could drop in an example file.  eg, at the end of a *.py code example we could have some simple markup like (not wed to the format, just illustrating)::</div>


<div><br></div><div>  # _gallery_ </div><div>  # topics: histograms, colormaps</div><div>  # rst: See :func:`~matplotlib.pyplot.hist` and :ref:`transforms_tutorial` for more info</div><div>  </div><div>
<br></div><div>and then the build process could drop it in a relevant section (or two) for the gallery.  Although the format is open to discussion, as the mockup illustrates we could support some additional rst style meta linkage to other docs, eg so the image/code pages could contain links to the api or other docs that the example illustrates.  Anything that is curated (and presumably we would comment and clean these as we tag them) would show up at the top of the gallery in the appropriate section, and we would have everything at the end in &#39;the weeds&quot; so all the examples make it on to the page, but the stuff at the top is organized and clean.  We could support a section of example markup that is full blown sphinx/rest, so for each page that is already image + code, we could optionally have a section that is full-blown-rest that describes the example with relevant links to the rest of the docs. This would give us not only curated sections, as Ben&#39;s pull request already does, but lots of useful metadata on top.</div>


<div><br></div><div>I do believe it is important that even non-curated examples show up &quot;in the weeds&quot; since curating is not something we can count on and there is value in the gallery as it is showing *everything* even if it has not been blessed.  But if we can fix what the typical user sees *first*, and then show everything else after that, it will be an improvement.</div>

<div><br></div><div>I&#39;ll work with Ben on some of these ideas and maybe I can sprint on this at pydata with Ben remotely and any locals who are interested.</div><div><br></div><div>JDH</div></div>