#17498: Pictures in the doc through ".. plot::" directive
-------------------------------------+-------------------------------------
Reporter: ncohen | Owner:
Type: enhancement | Status: needs_work
Priority: major | Milestone: sage-6.5
Component: documentation | Resolution:
Keywords: | Merged in:
Authors: Nathann Cohen, | Reviewers: Nathann Cohen, John
John Palmieri | Palmieri
Report Upstream: N/A | Work issues:
Branch: public/17498 | Commit:
Dependencies: #17508 | d7ae73cdec62e1d461fb951ef962746ddbdfd1b7
| Stopgaps:
-------------------------------------+-------------------------------------
Changes (by tmonteil):
* status: positive_review => needs_work
Comment:
Hi,
sorry for not being reactive, i am quite seek currently so the time i can
spend on Sage is lowered.
Replying to [comment:43 ncohen]:
> I do not know how to do that. At first I thought that it would be
impossible without rewriting matplotlib's plot directive, but then it
seems that it accepts a 'nofigs' option to do just that. I have no idea
how to change its value, however (we cannot touch the file directly, it is
not Sage code)
Not knowing how to fix this issue is not a sufficient condition to let the
size of every Sage binary explode (nor putting the ticket back to
needs_review as if no solution implies no problem). I was not claiming
that **you** should fix it yourself, i was claiming that **the ticket**
needs work, working on a ticket is a collaborative task, and there is no
reason to merge something that is not ready.
> > - The new `sphinx_plot` function is not documented nor tested.
>
> Well, it is not even a function but a string.
The `plot_pre_code` string could be an import statement of a genuine
doctested function, currently the code of the function is within a
configuration file, instead we could have a shorter `plot_pre_code` in
`src/doc/common/conf.py` and a genuine `sphinx_plot` function in
`src/sage/plot/misc.py` (say).
> And I do not see what you want me to test, the function returns no
output.
For example, we could test the existence of the file and its timestamp (in
case the image comes from an older build), its size (dimensions), the
color of some pixels in a quite predictible image ?
The plot directive seems not a sphinx standard, and i am not sure
matplotlib will not change its behaviour, or remove it, rename it (e.g. if
sphinx incorporate it with another name). Hence, there should perhaps be a
way to report something if the drawing goes wrong.
What is less clear to me is how to trigger the test (only after a docbuild
that used pictures).
> It would be nice, but I have no idea how to do that you want of me.
I would like to clearly avoid some misunderstanding: i am not expecting
some additional work from you (nor judging the quality of your code or
whatever), only trying to contribute to a ticket that should add more
features than problems within Sage.
Back to the main issue, John's current fix is a good step, but it does not
solve the fact that when we run `make` to build Sage, the doc is built
with pictures with no possibility to avoid it, and then we have to rebuild
the doc again to remove them.
I see various points to make John's fix work better:
- the way it is currently written, it is uselsss for the user to set the
`SPHINX_INCLUDE_PLOTS` environment variable because it is overwritten by
the `builder.py` script in any case. It could be better to use this
variable if the user defined it, so that the user could avoid building the
wrong documentation by typing `export SPHINX_INCLUDE_PLOTS=no` before
doing a `make`. One possibility is to document this variable and to
overwrite it only if `--no-pix` is explicitely stated.
- Note that in Sage, environment variables usually get values `yes/no`
instead of `True/False`, and their name start with `SAGE_`.
- Instead of adding a new `html-no-pix` FORMAT for the docbuild command,
it could be better to add a `--no-pix` OPTION (or perhaps `--no-plot` ?).
See `sage -docbuild` for the documentation. This is more consistent with
the existing `--no-pdf-links` or `--no-colors` options, but also allows to
pass the `--no-pix` (or whatever) option in the Makefile calls via the
`SAGE_DOCBUILD_OPTS` command.
--
Ticket URL: <http://trac.sagemath.org/ticket/17498#comment:57>
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.
