#170 Patch proposal to parsers/rst/directives/images.py

[Fernando Libonati]

There Docutils' team, I want to propose a patch to add a new "ascii" option to the image directive, to replace a "not-found" image file with an "ascii-art" image. This could be useful for make the documentation clearer, when using the image or figure directives, adding an 'ascii-art' representation of the final image.

Example of a docstring for a Cython extensión class, the :ascii: option could include any ascii-art version of the final image.

"""
.. code:: python

   b = module.Math2d(name: str, function: str)

.. _fig_NonLinear_Math2d:

.. figure:: ./images/Math2d.png
   :align: center
   :alt: Non-Linear / Math2d block
   :ascii:
       Math2d
       +---------+
       > X       |
       |   f(X,Y)>
       > Y       |
       +---------+

   Non-Linear / Math2d

Properties:


- function: name of the function (read-only)

.. warning::
    This block does not accept initial conditions propagation (yet).
"""

If the "./images/Math2d.png" is not available, it will be replaced with the text version of the image, that is not all, but something.

[Günter Milde]

What use case do you have in mind?
In the rST source, ASCII art in a comment would save the same purpose.

At what stage should the "not found" test happen?
HTML requires the image to be available when viewing,
LaTeX requires the image to be available at the LaTeX run,
ODT at rst2odt conversion time (?).

[Fernando Libonati]

I'm thinking in using the docstring for the internal doc and to produce the html with autoclass and automethod. As there are lots of images to produce, and we have no time to do it now, the patch will allow us to produce an html that is "usable" ... and when we have time to produce the final PNGs they will replace the 'ascii-art' version.

I've added an example of how does it looks in the html result.

It is a good advice to use the ascii-art as a comment, but if the image file (e.g. PNG) is not present, the produced html will include a reference to and unexistent image, and will force the need to produce it to release the documentation.

I've only test the idea in HTML, but think that the proposed patch will work in LaTeX and ODTs, because I replace the image reference with nodes.literal_block(self.options['ascii'], self.options['ascii']). So at the end, the unexistent image will not be a problem.

[Günter Milde]

I see you have a valid use case, but I am not sure the proposed patch is the best solution for Docutils (e.g. image files may be specified by an URL that is different from their file path.)
The patch is too fragmentaric for me to tell more.¹

The aafigure extension may be an even better solution. It can generate image files from embedded ascii-art. This way you have ASCII art in the source and nice images in the output without the need to produce them separately.
pypi.org/project/aafigure/

¹ A complete patch would have to include what file(s) are changed,
tests and documentation for the new option.

Thank you for sharing your extension and ideas.

[Günter Milde]

The use-case is too special to merit an additional option for the "image" directive and an additional attribute for the ´` Doctree element.
We may help if you are interested implementing it in a custom parser and writer.

Thank you for sharing your idea.