I was wondering if there are any defined policies or procedures for
generating multiple output files in docutils. An obvious use case is
writing html to multiple files, but the use case that I'm more
interested in at the moment has to do with generating auxilliary
files, such as images. In particular, we can define a number of
useful directives that generate images based on textual input... e.g.:
- render latex math formulae
- render graphviz dot graphs
- render strings like (S (NP John) (VP (V likes) (NP Mary))) as a
- directives used by epydoc to draw relevant graphs & diagrams,
class hierarchies, call graphs, package trees, import graphs,
So I was wondering what the best way to do this is. Restricting
myself to the image generation, I can see a few possible approaches:
1. create a temporary directory when rendering; write images
to that temporary directory; and let the writer know where the
temporary directory is. The image nodes would have a new
attribute, tempfilename, instead of url. Writers would copy the
image out of the temp directory, or include it directly, as
necessary. The temporary directory would be cleaned up
automatically. If output is not being written to a file, and the
images can't be included directly, then fail.
2. Specify an output directory during the parsing phase, which will
be the same directory as the output file. (If we're not outputting
to a file, then fail.) Use the filename (with no path info) as the
url of the image, and assume that the writer will find it.
3. when parsing, render images into memory, rather than into a file.
images will have a new 'data' attribute (and probably a mime-type?)
to contain the actual data. Writers are responsible for writing
data to a file, or including it in their output as appropriate.
writer is unable to do so (e.g., if the html writer is used and
is a string, then fail.)
There are probably other options too, but these are the ones that
came to mind. The latex-rendering code in the sandbox does something
approximating option (2). Option (3) is the most flexible, and feels
the "cleanest" to me, but it might have unreasonable memory
requirements. Between these, I guess I'd prefer option (1). Thoughs?
p.s., currently, epydoc doesn't actually render the graphs when
parsing; instead, it waits until the docstring is rendered. This is
because most of the directives (e.g., class diagrams) may need
information that hasn't been gathered yet at the time the docstring