documentation: Improve sphinx_plot to create scalable graphics

[mkoeppe]

The function sphinx_plot, introduced in #17498 to support the .. PLOT:: directive provided by the matplotlib sphinx extension, creates all graphics by saving to a temporary PNG file first.

This ticket improves this function so that 2d graphics (including GraphicsArrays) are shipped out directly via matplotlib. In this way, proper SVG graphics can be generated for the HTML documentation.

[mkoeppe]

New commits:

​02c5590

Improve sphinx_plot to create scalable graphics

[jhpalmieri]

The individual plots look good. It's a little quicker than the current way of building the documentation, and it takes up a little less disk space.

[jhpalmieri]

I think this looks okay, but I would like more opinions.

[kdilks]

I checked the once case where I remember using a Sphinx plot in my documentation (Fully Packed Loops), and it works fine there. Is there a good place to check to see how the GraphicsArray? works?

[mkoeppe]

Replying to kdilks:

I checked the once case where I remember using a Sphinx plot in my documentation (Fully Packed Loops), and it works fine there. Is there a good place to check to see how the GraphicsArray? works?

The documentation for sage.plot.plot.graphics_array has an example plot.

[kdilks]

Checked those, everything looks good to me. The svg files are taking up marginally more space than the original png files for me, but not enough to be concerning (71 vs 63 kb for plot-24, 45 vs 34 kb for plot-25 in the sage.plot.plot.graphics_array documentation).

[jhpalmieri]

The advantage, disk-space wise, is I see a bunch of PDF files in the old version but smaller svg files in the new version. I also see two versions of png files in the old version and only one in the new.

[mkoeppe]

I have only tested generating HTML documentation. I don't know what other formats are expected to work. In particular I haven't tried to build the PDF documentation.

[jhpalmieri]

With vanilla Sage, I get PDF files in local/share/doc/sage/inventory/en/reference/plotting/sage/graphs/ when I'm building the html docs. For example:

  -rw-r--r--  1 palmieri staff 254903 Jan 24 19:51 graph_plot-1.hires.png
  -rw-r--r--  1 palmieri staff 215503 Jan 24 19:51 graph_plot-1.pdf
  -rw-r--r--  1 palmieri staff  60166 Jan 24 19:51 graph_plot-1.png
  -rw-r--r--  1 palmieri staff     34 Jan 24 19:51 graph_plot-1.py
  ...

With the branch here:

  -rw-r--r--  1 palmieri staff  38735 Jan 24 20:03 graph_plot-1.png
  -rw-r--r--  1 palmieri staff     34 Jan 24 20:03 graph_plot-1.py
  -rw-r--r--  1 palmieri staff  18445 Jan 24 20:03 graph_plot-1.svg

[kdilks]

I was also only checking the HTML documentation, and in a not-so-thorough way. I'll look a little more closely to double check on all the files that get created, and also try building the pdf documentation.

[git]

Branch pushed to git repo; I updated commit sha1. New commits:

​9daa32e

Fixup for scalable graphics in PDF docs

[mkoeppe]

With this fix, also the PDF documentation now has the scalable graphics. Needs review...

[jhpalmieri]

Regarding the change

-def sphinx_plot(plot):
+def sphinx_plot(graphics, **kwds)

is sphinx_plot called with extra arguments anywhere (yet)?

It all works for me, but I don't have time to look carefully at the rest of the code. At a glance it looks okay, but if someone else is willing to take a closer look, that would be great.

[mkoeppe]

Replying to jhpalmieri:

Regarding the change

-def sphinx_plot(plot):
+def sphinx_plot(graphics, **kwds)

is sphinx_plot called with extra arguments anywhere (yet)?

It is not yet used in the sage documentation, but is crucial for GraphicsArrays, which do not have a way to store show options. (One of many defects of GraphicsArrays.) I use it in my package to make graphics array plots with particular figure sizes. Example: ​http://mkoeppe.github.io/cutgeneratingfunctionology/doc/html/procedures.html

[jhpalmieri]

At some point (not necessarily on this ticket), would it be a good idea to move sphinx_plot into the Sage library, along with a docstring, examples, and doctests, and then essentially just import it in conf.py? So change plot_pre_code to equal

from sage.all_cmdline import *
from sage.plot.sphinx_plot import sphinx_plot

Or is there some good reason to keep it where it is?

[mkoeppe]

Replying to jhpalmieri:

At some point (not necessarily on this ticket), would it be a good idea to move sphinx_plot into the Sage library, along with a docstring, examples, and doctests, and then essentially just import it in conf.py? So change plot_pre_code to equal

from sage.all_cmdline import *
from sage.plot.sphinx_plot import sphinx_plot

Or is there some good reason to keep it where it is?

In a follow-up ticket, it could be good to refactor it as follows: Remove the sphinx_plot function completely and instead giving every graphics object (including GraphicsArrays and the 3D graphics objects) a method to_pyplot (or similar) that will put the object in a pyplot figure.

This would be useful for interoperating sage graphics with pure matplotlib.pyplot code, not just for Sphinx.

[jhpalmieri]

Okay, I'm happy with this.

[mkoeppe]

Thank you!

[mkoeppe]

Replying to mkoeppe:

In a follow-up ticket, it could be good to refactor it as follows: Remove the sphinx_plot function completely and instead giving every graphics object (including GraphicsArrays and the 3D graphics objects) a method to_pyplot (or similar) that will put the object in a pyplot figure.

This would be useful for interoperating sage graphics with pure matplotlib.pyplot code, not just for Sphinx.

Follow-up ticket for this: #27276

[mkoeppe]

Follow-up: #27481