[PATCH 2/6] docs-rst: automatically convert Graphviz and SVG images

[Markus Heiser]

Am 02.03.2017 um 08:12 schrieb Daniel Vetter <daniel at ffwll.ch>:

> On Wed, Mar 01, 2017 at 12:56:36PM -0300, Gabriel Krisman Bertazi wrote:
>> Daniel Vetter <daniel.vetter at ffwll.ch> writes:
>> 
>> Hi Daniel,
>> 
>>> +    if dst_fname:
>>> +        name = dst_fname[len(out_dir) + 1:]
>>> +        # the builder needs not to copy one more time, so pop it if exists.
>>> +        translator.builder.images.pop(img_node['uri'], None)
>>> +        img_node['uri'] = dst_fname
>>> +        img_node['candidates'] = {'*': dst_fname}
>>> +
>>> +        mkdir(path.dirname(dst_fname))
>>> +
>>> +        if in_ext == '.dot':
>>> +            verbose('convert DOT to: {out}/' + name)
>>> +            dot2format(src_fname, dst_fname)
>>> +
>>> +        elif in_ext == '.svg':
>>> +            verbose('convert SVG to: {out}/' + name)
>>> +            svg2pdf(src_fname, dst_fname)
>> 
>> Small nit, but, shouldn't you add dst_fname to img_node only if
>> dot2format or svg2pdf was successful?
> 
> I kinda assumed they're always successful, since the media documentation
> build already requires them.

SHORT:

At this time (Phase 1: Reading), the internal doctree is build and
with these two lines:

>>> +        img_node['uri'] = dst_fname
>>> +        img_node['candidates'] = {'*': dst_fname}


the image is added as wildcard "*" to the doctree. 

Later (Phase 4: Writing), when the output is generated from
doctree, the (pdf-/html-) builder will search for the best
existing "*" candidate, e.g. "*.svg" for html and "*.pdf"
for LaTeX.

MORE VERBOSE:

To see/understand the whole play we have to know that Sphinx/docutils
has Build Phases: 

* http://www.sphinx-doc.org/en/stable/extdev/tutorial.html#build-phases

"""
Phase 1: Reading
In Phase 1, all source files (and on subsequent builds, those that are new or changed) are read and parsed. This is the phase where directives and roles are encountered by docutils, and the corresponding code is executed. The output of this phase is a doctree for each source file"""
...

Phase 4: Writing
This phase converts the resolved doctrees to the desired output format, such as HTML or LaTeX. This happens via a so-called docutils writer that visits the individual nodes of each doctree and produces some output in the process.
"""

The visitor for handling kernel_image, kernel_render and kernel_figure
directives are analog, so lets look at the simple one::

+def visit_kernel_image(self, node):    # pylint: disable=W0613
+    """Visitor of the ``kernel_image`` Node.
+
+    Handles the ``image`` child-node with the ``convert_image(...)``.
+    """
+    img_node = node[0]
+    convert_image(img_node, self)

this is the visitor, for building the internal doctree. The visitor
calls convert_image() with img_node as first argument.

The convert_image() first evals a new dst_fname for image
types which are covered by:

+    dst_fname     = None
...
+    if in_ext == '.dot':
+        dst_fname = path.join(out_dir, fname + '.pdf')
....
+
+    elif in_ext == '.svg':
+        if translator.builder.format == 'latex':
+            dst_fname = path.join(out_dir, fname + '.pdf')

Consider that dst_fname is always in the out_dir. So, if this image type
is covered by convert_image(), we have to remove the old image from
builder's image-stack (the stack is outside of the node-tree).

+    if dst_fname:
+        name = dst_fname[len(out_dir) + 1:]
+        # the builder needs not to copy one more time, so pop it if exists.
+        translator.builder.images.pop(img_node['uri'], None)
+        img_node['uri'] = dst_fname
+        img_node['candidates'] = {'*': dst_fname}


So you might already guess, this image handling method is bonded
only to Phase 1 and we do not need to touch any builder (Phase 4).
The central point is the last line:

+        img_node['candidates'] = {'*': dst_fname}

The other important thing is, that generated files (dst_fname) are 
always in the out_dir. This is needed, since kernel-build should not
pollute the src_folder. 


@Daniel: Thanks a lot for your:

v2: s/DOC/DOT/ in a few places (by Daniel).
v3: Simplify stuff a bit (by Daniel):

I haven't had time to test and I can't promise that I will
find the time for. So, for the first, take my Acked-by.

--Markus--