pictures in the reference manual?
John H Palmieri
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.
John
David Joyner
I wonder if another possibility is to simply have a
local link which notebook users could click on?
I also wonder what would happen on command line if you
typed "plot?", where the docstring for plot had a picture?
William Stein
Should we allow the inclusion of pictures in the reference manual?
Yes, definitely. The only possible reason not to have pictures is not being able to figure out how to include pictures.
William
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.
Nice.
William
Pat LeSmithe
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.
Then for notebook introspection, we can run Sphinx "as usual" in the doc
cache directory (cf. #5653), inserting the correct img src URLs via
macros (if possible) or by post-processing the output.
If I build the bordeaux_2008 document, which contains the reST directive
.. image:: birch.*
in the absence of birch.png, Sphinx 0.5.1 complains, but it still inserts
<img alt="birch.*" src="birch.*" />
into the output.
If we take this approach, I think we should pass to cell.py's
set_introspect_html() the target object's fully qualified name. With
this or similar information, we could also convert broken
cross-references to
async_request(worksheet_command('introspect'),
evaluate_cell_callback, {id: id, before_cursor: query,
after_cursor: ''});
with the appropriate cell id and query. Part of #6001's experimental
tear-out support is a mini-toolbar to change the font size for a
docstring, limit its height, tear it out, close it, etc. It might be
useful to add options to browse to the next/previous definition in the
ambient module. I don't know if it's easy to find these objects in Python.
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?
Another interesting possibility is image-based "doctesting." I *think*
VTK has a suite of about 1000 tests, many of which generate images of
reasonable size, reasonably quickly. An image diff utility compares
each to a baseline image, with some tolerance, to grade the tests.
John H Palmieri
On Aug 5, 6:16 pm, Pat LeSmithe <qed...@gmail.com> 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.
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?
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
Pat LeSmithe
> 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",
What if we searched for and saved all of the image directives before
running Sphinx and inserted the correct paths afterward? We could
verify that the file base names agree on some metric.
Alternatively, we could extract a path from the "**File:**" field
inserted by server.support.docstring() or source_code(). But this could
make it difficult to include images from other modules.
With custom Sphinx directives, we could do the same for, e.g., movies
and PDF files. It might take a "bit" more work to insert interactive
output.
Is there an open ticket for this topic?
John H Palmieri
On Aug 7, 9:33 am, Pat LeSmithe <qed...@gmail.com> wrote:
> John H Palmieri wrote:
> > 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",
>
> What if we searched for and saved all of the image directives before
> running Sphinx and inserted the correct paths afterward? We could
> verify that the file base names agree on some metric.
names like "pic1.png", "pic2.png", etc., and then working out which
one is which could be annoying. Another idea: maybe as part of
building the reference manual, create a symlink from doc/en/reference/
pictures to doc/output/html/en/pictures. Then we can easily access
the images: just change
../../pictures/...path.../blah.png (or /pictures/...path.../
blah.png, which would also be a valid way to specify the file)
to
http://localhost:8000/doc/static/pictures/...path.../blah.png
This is an easy regular expression operation.
> Alternatively, we could extract a path from the "**File:**" field
> inserted by server.support.docstring() or source_code(). But this could
> make it difficult to include images from other modules.
>
> With custom Sphinx directives, we could do the same for, e.g., movies
> and PDF files. It might take a "bit" more work to insert interactive
> output.
>
> Is there an open ticket for this topic?
John
John H Palmieri
<http://trac.sagemath.org/sage_trac/ticket/6685>
Pat LeSmithe
There is a companion ticket for converting reference manual pages into
live worksheets