Pat LeSmithe wrote: > Jason Grout wrote: >> Pat LeSmithe wrote: >>> The immediate context, at least for me, is automatically generating >>> images in the documentation (#6847, nothing yet). Currently, this uses >>> a modified version of a matplotlib Sphinx directive with a new comment >>> modifier, e.g. >>> >>> .. plot:: >>> >>> sage: G = plot(cos, -5, 5, thickness=5, color='green') >>> sage: P = polygon([[1,2], [5,6], [5,0]], color='red') >>> sage: G + P # image >>> sage: for i in xrange(10): >>> ... i * i >>> sage: polygon([(-x,y) for x,y in P[0]], color='blue') #image >>> sage: circle((0,0), 3, rgbcolor=(0.8,0,0.7), aspect_ratio=1) # >>> image >>> >> So are you proposing a way to just insert images, without showing the >> code (or maybe showing the code in a special way, e.g., clicking on the >> plot reveals the code or something)? Or are you saying that having the >> .. plot:: makes it so that sphinx will actually run the code, as opposed >> to just a ::, where sphinx just formats the code, but does not run it? > > The auto-generated matplotlib examples and gallery are first-order > approximations and inspiration: > > http://matplotlib.sourceforge.net/examples/api/histogram_demo.html > http://matplotlib.sourceforge.net/users/transforms_tutorial.html > http://matplotlib.sourceforge.net/gallery.html
Yep, those are the things I'm thinking of too. > > For the Sage documentation, the plot directive might act somewhat as a > filter that, depending on the builder (HTML, LaTeX): > > * Runs the code. > > * Passes along the code, unchanged or transformed, for further > processing by Sphinx or uses it in a more interesting way, as you suggest. > > * For each image output by the block: > > + Saves it in the desired formats, e.g., low/hi-res PNG, SVG, PDF, etc. > + Inserts ".. image::" for an inline image, passing along the options > for this directive. > + Inserts reST source for hyperlinks to other formats. > + Saves and adds a link to plain-text code. Or a copy-to-clipboard link? > + Copies the linked-to files to an output directory. (Sphinx proper > copies the inline image.) > > * For each non-static plot output by the block: > > + Saves the JavaScript or Jmol data. > + Inserts markup for embedding, perhaps inside an initially collapsed > div. > + Tells Sphinx to add required script elements. > + Copies the data to an output directory. > > Sorry, if this is too much detail. The non-static case is still just > conjecture, but it should be easier to implement with your insight below. Wow, your ideas are fantastic. I'm really glad we have someone as capable as you working on this. > >> Is "#image" necessary in the above example? It shouldn't be---it should >> be straightforward to change the default viewer to generate an image for >> sphinx if sphinx is processing the code. > > That's almost surely a *much* better way to go. Thanks! How about using > > sage.plot.plot.DOCBUILD_MODE=True > > and a couple more prepended global variables that set a base filename > and list of output formats? Currently, the base name is the MD5 hash of > the code block. That sounds like a great way to approach things, and naturally builds on the EMBEDDED_MODE and other variables already in sage/plot/plot.py. Thanks, Jason -- Jason Grout --~--~---------~--~----~------------~-------~--~----~ To post to this group, send an email to sage-devel@googlegroups.com To unsubscribe from this group, send an email to sage-devel-unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/sage-devel URL: http://www.sagemath.org -~----------~----~----~----~------~----~------~--~---
