#6685: [with patch, needs review] include pictures in the reference manual and
notebook introspection
---------------------------+------------------------------------------------
Reporter: jhpalmieri | Owner: tba
Type: enhancement | Status: new
Priority: major | Milestone: sage-4.1.2
Component: documentation | Keywords:
Reviewer: | Author:
Merged: |
---------------------------+------------------------------------------------
Comment(by mpatel):
By the way, and for what it's worth, #6694 was first motivated by the
desire to interactively produce images for the reference manual. It is a
fun way to explore the many mathematical capabilities of Sage, although
evaluating all cells can sometimes severely test a browser.
But adapting the docbuild and/or doctesting frameworks seems to be a
significantly better approach for generating the images in bulk. Does
`sage -t`, when it's not invoked with `-randorder`, keep track of the
index of a test cell in a module? If so, perhaps we can retain any
produced images, rename them in a systematic way, and splice appropriate
`.. image::` tags into the docstrings. Since this is invasive, we can
make this a separate command, e.g., `sage -imagebuild`, for library
authors. Are regular expressions the safest way to check for and remove
or update existing tags?
An alternative, possibly cleaner way is to extend Sphinx so that it
generates and inserts an image dynamically, whenever it finds an `..
autoimage::` directive. It may be simplest to include as a "required
option" the precise code to make the image. This will increase the time
it takes to build the manual, unless we cache the figures effectively.
(Sphinx's [http://sphinx.pocoo.org/ext/doctest.html doctest extension] may
or may not help here.)
Some library authors may wish to include a specific set of pictures in the
reference manual, in part to showcase their code's abilities. If a media
file is not superfluous, but it takes a long time to generate with Sage,
why not include and track it as a binary? We could put some limits on
file sizes or even offer to host them on sage.math and embed them in the
manual.
My chief worry is maintaining the correctness and consistency of any
pictures with the code examples. Adding image diffs to doctesting (with
some tolerance) might help, but we would still need to track the binary
"masters." Anyway, this might force contributors to pay attention.
--
Ticket URL: <http://trac.sagemath.org/sage_trac/ticket/6685#comment:8>
Sage <http://sagemath.org/>
Sage: Creating a Viable Open Source Alternative to Magma, Maple, Mathematica,
and MATLAB
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"sage-trac" group.
To post to this group, send email to [email protected]
To unsubscribe from this group, send email to
[email protected]
For more options, visit this group at
http://groups.google.com/group/sage-trac?hl=en
-~----------~----~----~----~------~----~------~--~---
