We can now have pictures in our documentation

203 views
Skip to first unread message

Nathann Cohen

unread,
Feb 18, 2015, 4:42:42 AM2/18/15
to Sage devel
Hellooooooooo everybody,

This email is just here to share the news that our documentation can
now "relatively easily" be improved by sage-generated pictures. This
feature appeared in Sage 6.6.beta0.

To draw the function x->x^2 in a docstring, you have to write the following:

.. PLOT::

sphinx_plot(plot(x^2))

If you want to see Petersen's graph instead, write:

.. PLOT::

g = graphs.PetersenGraph()
sphinx_plot(g.plot())

Now we have behind us a loooooooong history of docstrings which would
be 10x easier to understand with pictures. Let's get it fixed, and
write the future ones with more colors.

Have fuuuuuuuuun,

Nathann

Dominique Laurain

unread,
Feb 18, 2015, 3:31:02 PM2/18/15
to sage-...@googlegroups.com
Bravo et merci....

jplab

unread,
Mar 17, 2015, 10:50:11 AM3/17/15
to sage-...@googlegroups.com
This looks very powerful!!!

Thank you very much!!

I have a few questions (you probably see me coming with these...):

- Can this be used to show pdf pictures obtained by (tikz) latex code?

- In general, can sage show a pdf picture as a plot option? (Something in the vain of http://www.liafa.univ-paris-diderot.fr/~labbe/blogue/2012/11/using-sage-graphviz-dot2tex-tikz-tikz2pdf-to-draw-a-graph/)

If both is possible, the documentation would benefit greatly!

JP

Nathann Cohen

unread,
Mar 18, 2015, 5:16:44 AM3/18/15
to sage-...@googlegroups.com
Helloooooooo,


- Can this be used to show pdf pictures obtained by (tikz) latex code?

HMmmmm O_o

Well, not as it is right now. You should be able to plot anything that has some .plot command that works through matplotlib. If you can create a matplotlib object from a pdf file perhaps, but there are tricks to find that I do not know ^^;

Nathann 

Robert Bradshaw

unread,
Mar 19, 2015, 1:18:28 AM3/19/15
to sage-devel
Cool. Any reason we couldn't just detect the standard plot() command
in a PLOT section?
> --
> You received this message because you are subscribed to the Google Groups
> "sage-devel" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to sage-devel+...@googlegroups.com.
> To post to this group, send email to sage-...@googlegroups.com.
> Visit this group at http://groups.google.com/group/sage-devel.
> For more options, visit https://groups.google.com/d/optout.

Nathann Cohen

unread,
Mar 19, 2015, 4:19:05 AM3/19/15
to Sage devel
Helloooooooooooo,

> Cool. Any reason we couldn't just detect the standard plot() command
> in a PLOT section?

Technically, I guess that everything is possible. Now, the immediate
reason is that this is implemented through something called a "sphinx
directive" [1], and that I have not figured out how to write one from
scratch.

Thus, what we use currently is the 'plot directive' [2] implemented in
matplotlib. Not surprisingly, it is made to work for.... matplotlib
drawings. And this is what limits us at the moment.

For this reason, when using that directive in Sage we must use some
function called 'draw_sphinx' outputs <the Sage object we want to
plot> to a .jpg file, then loads that .jpg file with matplotlib. If we
can do the same with .pdf file we are good.

And if we want something more 'native' we will need to implement a
sphinx directive ourselves. I tried, and I was scared :-P

Nathann

[1] http://sphinx-doc.org/rest.html#directives
[2] http://matplotlib.org/sampledoc/extensions.html#inserting-matplotlib-plots

Eric Gourgoulhon

unread,
Jun 30, 2015, 4:44:48 AM6/30/15
to sage-...@googlegroups.com
Hi Nathann,

Many thanks for this very useful enhancement!
I am using it in #18528 and have noticed that the Sage preparser is not invoked in the series of instructions between ".. PLOT::" and "sphinx_plot(...)": we cannot use the "<>" trick and we have to write "x**2" instead of "x^2". Is there a way to turn the Sage preparser on? Anyway, this is not a big annoyance and we can live with it.
Thanks again!

Eric.

Nathann Cohen

unread,
Jun 30, 2015, 5:20:14 AM6/30/15
to Sage devel
> I am using it in #18528 and have noticed that the Sage preparser is not
> invoked in the series of instructions between ".. PLOT::" and
> "sphinx_plot(...)": we cannot use the "<>" trick and we have to write "x**2"
> instead of "x^2". Is there a way to turn the Sage preparser on? Anyway, this
> is not a big annoyance and we can live with it.

I really have no idea O_o

I'd look into 'preparser(True)' but I am not very sure that it would
work. Others here may e more knowledgeable, though O_o

Sorryyyyyyyyyyyyyyy,

Nathann

Eric Gourgoulhon

unread,
Jun 30, 2015, 7:51:41 AM6/30/15
to sage-...@googlegroups.com
Thanks for your prompt answer. As I said, this is not a big deal, since everything can be reformulated without the Sage preparser.

Btw, I have another remark: in the online reference manual on sagemath page, clicking on "(Source code)" next to a plot results in a 404 error, see e.g. the plot of the Petersen graph at
http://doc.sagemath.org/html/en/reference/graphs/sage/graphs/generic_graph.html#sage.graphs.generic_graph.GenericGraph.longest_path

Best wishes,

Eric.

Nathann Cohen

unread,
Jun 30, 2015, 10:09:53 AM6/30/15
to Sage devel
Yooooooooo !

> Btw, I have another remark: in the online reference manual on sagemath page,
> clicking on "(Source code)" next to a plot results in a 404 error

That's fixed:
http://trac.sagemath.org/ticket/17618

Though the online manual will still display them until the next
'stable' release (when the doc will be updated).

Have fuuuuuuuuun,

Nathann
Reply all
Reply to author
Forward
0 new messages