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.
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.
--~--~---------~--~----~------------~-------~--~----~
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
-~----------~----~----~----~------~----~------~--~---
