On Aug 5, 6:16 pm, Pat LeSmithe <[email protected]> wrote:
> John H Palmieri wrote:
> > Should we allow the inclusion of pictures in the reference manual? We
> > could have a directory
>
> > SAGE_ROOT/devel/sage/doc/en/reference/pictures
>
> > and then in docstrings in the Sage library code, a line like
>
> > .. image:: ../../pictures/sphere.png
>
> > would include the picture in the reference manual. (This is for a
> > file in sage/sage/MODULE/FILE.py; adjust the number of "../"s for
> > files in sage/sage/MODULE/SUBDIRECTORY/FILE.py, etc.) I haven't
> > figured out how to get the pictures to appear when you view the
> > docstrings in the notebook, but I haven't worked at it very much.
>
> I think one way to go, as we do already for HTML files, is to make the
> image directory accessible to Sphinx on disk for the reference manual
> proper, but also to map the directory to some server address, in twist.py.
If they are included in the reference manual by ".. image:: blah.png"
directives, then when the docs are built, the images are all copied to
sage/doc/output/html/en/reference/_images, and since these are
viewable in the live and static versions of the documentation, the
pictures should be accessible already. In the cached html version of
the docstring (in .sage/sage_worksheets/doc), I can edit the path for
the image, putting in "http://localhost:8000/doc/static/reference/
_images/blah.png", and the image appears.
So for notebook introspection, we need to replace the old path with
the appropriate URL; then the issue is that the images may get renamed
when the docs are built. For example, I was imagining that the
"pictures" directory would have subdirectories, for example, one from
each Sage module. If there are files "pictures/homology/simplex.png"
and "pictures/geometry/simplex.png", each used in docstrings somewhere
in the Sage library, then these would be copied to something like
"reference/_images/simplex.png" and "reference/_images/simplex1.png",
and I don't know how to keep track of which one goes with which
docstring (other than scanning the html version of the reference
manual). I guess the other issue is that if there are pictures in
functions which are not included in the reference manual (__init__,
for example), then they would not be available.
[snip]
> I think the command-line output would, if we left it alone, contain the
> source line. Perhaps we can process that, too, in some way? Should the
> docstring not make essential use of the image?
I think that would be best. For example, in the file plot.py, a
docstring could look like
EXAMPLES: We construct a plot involving several graphics objects::
sage: G = plot(cos, -5, 5, thickness=5, rgbcolor=(0.5,1,0.5))
sage: P = polygon([[1,2], [5,6], [5,0]], rgbcolor=(1,0,0))
sage: G + P # show it
.. image:: ../../pictures/plot/cos_and_triangle.png
(The last line is the only change from the existing docstring.) Then
in the notebook or the reference manual, you see a nice picture; from
the command-line, you either see the ".. image" command, or we could
remove it (via the detex function). The command-line version would
then look just like it does now.
John
--~--~---------~--~----~------------~-------~--~----~
To post to this group, send an email to [email protected]
To unsubscribe from this group, send an email to
[email protected]
For more options, visit this group at http://groups.google.com/group/sage-devel
URLs: http://www.sagemath.org
-~----------~----~----~----~------~----~------~--~---
