#17498: Pictures in the doc through ".. plot::" directive
-------------------------+-------------------------------------------------
Reporter: | Owner:
ncohen | Status: needs_work
Type: | Milestone: sage-6.5
enhancement | Resolution:
Priority: major | Merged in:
Component: | Reviewers:
documentation | Work issues:
Keywords: | Commit:
Authors: | 361f9a8a79aa51fa1f0d39dc08be0a379fb9b30a
Nathann Cohen | Stopgaps:
Report Upstream: N/A |
Branch: |
public/17498 |
Dependencies: |
#17508 |
-------------------------+-------------------------------------------------
Changes (by tmonteil):
* status: needs_review => needs_work
Comment:
Replying to [comment:40 ncohen]:
> YOooooo ! Is anything else needed ?
Concerning requirements (i did not test the branch yet, only read its
content):
- This was already discussed in comments [comment:27] and [comment:28]:
there should be a way to turn this feature on/off from the `sage
-docbuild` and the `make doc` commands, since some binaries need to stay
small. For example, one could add a `htmlpng` (or whatever `htmlplot`,
through at some point one could insert e.g. svg images) docbuild format
(and also trigger the plotting for the existing `web` format), which leads
to calls like:
{{{
sage -docbuild reference htmlpng
}}}
- The new `sphinx_plot` function is not documented nor tested.
Concerning the discussion about the syntax, a possibility which could make
syntax more uniform (hence easier to remember) could be to have a similar
syntax as in passing options to the doctests, e.g.
{{{
::
graphs.PetersenGraph().plot() # plot
}}}
Actually, both syntax could coexist, because there are two use cases with
two different behaviors:
- a `..PLOT::` directive to insert plots within some classical text, so
that the code that builds the image does not appear, as for the currently
used `..image::` directive (see e.g. in
`src/sage/homology/simplicial_complex.py` and the
[http://sagemath.org/doc/reference/homology/sage/homology/simplicial_complex.html
resulting page]).
- a `# plot` comment within the doctests, so that plots appear as the
result of the doctest (resp. under the corresponding cell in the live
doc), while letting the code visible (resp. still executable in the live
cells).
Probably not for this ticket, we should take the opportunity to remove
hardcoded png images from the git tree that are used by the `..image::`
directive, and build them instead (at least for the plots that were
obtained with Sage). However, the old `..image::` hardcoded way had the
advantage that images do not depend on bugs, so there should be some way
to kind of test the automatically produced pictures (from their size?,
from similarities with previous build?), or at least to provide a way to
see them all at once to have a visual check before releasing and pushing
to the official doc.
--
Ticket URL: <http://trac.sagemath.org/ticket/17498#comment:42>
Sage <http://www.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 unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
Visit this group at http://groups.google.com/group/sage-trac.
For more options, visit https://groups.google.com/d/optout.
