468 lines
17 KiB
Python
468 lines
17 KiB
Python
|
"""Allow graphviz-formatted graphs to be included inline in generated documents.
|
||
|
|
"""
|
||
|
|
|
||
|
|
from __future__ import annotations
|
||
|
|
|
||
|
|
import posixpath
|
||
|
|
import re
|
||
|
|
import subprocess
|
||
|
|
import xml.etree.ElementTree as ET
|
||
|
|
from hashlib import sha1
|
||
|
|
from itertools import chain
|
||
|
|
from os import path
|
||
|
|
from subprocess import CalledProcessError
|
||
|
|
from typing import TYPE_CHECKING, Any
|
||
|
|
from urllib.parse import urlsplit, urlunsplit
|
||
|
|
|
||
|
|
from docutils import nodes
|
||
|
|
from docutils.parsers.rst import Directive, directives
|
||
|
|
|
||
|
|
import sphinx
|
||
|
|
from sphinx.errors import SphinxError
|
||
|
|
from sphinx.locale import _, __
|
||
|
|
from sphinx.util import logging
|
||
|
|
from sphinx.util.docutils import SphinxDirective
|
||
|
|
from sphinx.util.i18n import search_image_for_language
|
||
|
|
from sphinx.util.nodes import set_source_info
|
||
|
|
from sphinx.util.osutil import ensuredir
|
||
|
|
|
||
|
|
if TYPE_CHECKING:
|
||
|
|
from docutils.nodes import Node
|
||
|
|
|
||
|
|
from sphinx.application import Sphinx
|
||
|
|
from sphinx.config import Config
|
||
|
|
from sphinx.util.typing import OptionSpec
|
||
|
|
from sphinx.writers.html import HTML5Translator
|
||
|
|
from sphinx.writers.latex import LaTeXTranslator
|
||
|
|
from sphinx.writers.manpage import ManualPageTranslator
|
||
|
|
from sphinx.writers.texinfo import TexinfoTranslator
|
||
|
|
from sphinx.writers.text import TextTranslator
|
||
|
|
|
||
|
|
logger = logging.getLogger(__name__)
|
||
|
|
|
||
|
|
|
||
|
|
class GraphvizError(SphinxError):
|
||
|
|
category = 'Graphviz error'
|
||
|
|
|
||
|
|
|
||
|
|
class ClickableMapDefinition:
|
||
|
|
"""A manipulator for clickable map file of graphviz."""
|
||
|
|
maptag_re = re.compile('<map id="(.*?)"')
|
||
|
|
href_re = re.compile('href=".*?"')
|
||
|
|
|
||
|
|
def __init__(self, filename: str, content: str, dot: str = '') -> None:
|
||
|
|
self.id: str | None = None
|
||
|
|
self.filename = filename
|
||
|
|
self.content = content.splitlines()
|
||
|
|
self.clickable: list[str] = []
|
||
|
|
|
||
|
|
self.parse(dot=dot)
|
||
|
|
|
||
|
|
def parse(self, dot: str) -> None:
|
||
|
|
matched = self.maptag_re.match(self.content[0])
|
||
|
|
if not matched:
|
||
|
|
raise GraphvizError('Invalid clickable map file found: %s' % self.filename)
|
||
|
|
|
||
|
|
self.id = matched.group(1)
|
||
|
|
if self.id == '%3':
|
||
|
|
# graphviz generates wrong ID if graph name not specified
|
||
|
|
# https://gitlab.com/graphviz/graphviz/issues/1327
|
||
|
|
hashed = sha1(dot.encode(), usedforsecurity=False).hexdigest()
|
||
|
|
self.id = 'grapviz%s' % hashed[-10:]
|
||
|
|
self.content[0] = self.content[0].replace('%3', self.id)
|
||
|
|
|
||
|
|
for line in self.content:
|
||
|
|
if self.href_re.search(line):
|
||
|
|
self.clickable.append(line)
|
||
|
|
|
||
|
|
def generate_clickable_map(self) -> str:
|
||
|
|
"""Generate clickable map tags if clickable item exists.
|
||
|
|
|
||
|
|
If not exists, this only returns empty string.
|
||
|
|
"""
|
||
|
|
if self.clickable:
|
||
|
|
return '\n'.join([self.content[0]] + self.clickable + [self.content[-1]])
|
||
|
|
else:
|
||
|
|
return ''
|
||
|
|
|
||
|
|
|
||
|
|
class graphviz(nodes.General, nodes.Inline, nodes.Element):
|
||
|
|
pass
|
||
|
|
|
||
|
|
|
||
|
|
def figure_wrapper(directive: Directive, node: graphviz, caption: str) -> nodes.figure:
|
||
|
|
figure_node = nodes.figure('', node)
|
||
|
|
if 'align' in node:
|
||
|
|
figure_node['align'] = node.attributes.pop('align')
|
||
|
|
|
||
|
|
inodes, messages = directive.state.inline_text(caption, directive.lineno)
|
||
|
|
caption_node = nodes.caption(caption, '', *inodes)
|
||
|
|
caption_node.extend(messages)
|
||
|
|
set_source_info(directive, caption_node)
|
||
|
|
figure_node += caption_node
|
||
|
|
return figure_node
|
||
|
|
|
||
|
|
|
||
|
|
def align_spec(argument: Any) -> str:
|
||
|
|
return directives.choice(argument, ('left', 'center', 'right'))
|
||
|
|
|
||
|
|
|
||
|
|
class Graphviz(SphinxDirective):
|
||
|
|
"""
|
||
|
|
Directive to insert arbitrary dot markup.
|
||
|
|
"""
|
||
|
|
has_content = True
|
||
|
|
required_arguments = 0
|
||
|
|
optional_arguments = 1
|
||
|
|
final_argument_whitespace = False
|
||
|
|
option_spec: OptionSpec = {
|
||
|
|
'alt': directives.unchanged,
|
||
|
|
'align': align_spec,
|
||
|
|
'caption': directives.unchanged,
|
||
|
|
'layout': directives.unchanged,
|
||
|
|
'graphviz_dot': directives.unchanged, # an old alias of `layout` option
|
||
|
|
'name': directives.unchanged,
|
||
|
|
'class': directives.class_option,
|
||
|
|
}
|
||
|
|
|
||
|
|
def run(self) -> list[Node]:
|
||
|
|
if self.arguments:
|
||
|
|
document = self.state.document
|
||
|
|
if self.content:
|
||
|
|
return [document.reporter.warning(
|
||
|
|
__('Graphviz directive cannot have both content and '
|
||
|
|
'a filename argument'), line=self.lineno)]
|
||
|
|
argument = search_image_for_language(self.arguments[0], self.env)
|
||
|
|
rel_filename, filename = self.env.relfn2path(argument)
|
||
|
|
self.env.note_dependency(rel_filename)
|
||
|
|
try:
|
||
|
|
with open(filename, encoding='utf-8') as fp:
|
||
|
|
dotcode = fp.read()
|
||
|
|
except OSError:
|
||
|
|
return [document.reporter.warning(
|
||
|
|
__('External Graphviz file %r not found or reading '
|
||
|
|
'it failed') % filename, line=self.lineno)]
|
||
|
|
else:
|
||
|
|
dotcode = '\n'.join(self.content)
|
||
|
|
rel_filename = None
|
||
|
|
if not dotcode.strip():
|
||
|
|
return [self.state_machine.reporter.warning(
|
||
|
|
__('Ignoring "graphviz" directive without content.'),
|
||
|
|
line=self.lineno)]
|
||
|
|
node = graphviz()
|
||
|
|
node['code'] = dotcode
|
||
|
|
node['options'] = {'docname': self.env.docname}
|
||
|
|
|
||
|
|
if 'graphviz_dot' in self.options:
|
||
|
|
node['options']['graphviz_dot'] = self.options['graphviz_dot']
|
||
|
|
if 'layout' in self.options:
|
||
|
|
node['options']['graphviz_dot'] = self.options['layout']
|
||
|
|
if 'alt' in self.options:
|
||
|
|
node['alt'] = self.options['alt']
|
||
|
|
if 'align' in self.options:
|
||
|
|
node['align'] = self.options['align']
|
||
|
|
if 'class' in self.options:
|
||
|
|
node['classes'] = self.options['class']
|
||
|
|
if rel_filename:
|
||
|
|
node['filename'] = rel_filename
|
||
|
|
|
||
|
|
if 'caption' not in self.options:
|
||
|
|
self.add_name(node)
|
||
|
|
return [node]
|
||
|
|
else:
|
||
|
|
figure = figure_wrapper(self, node, self.options['caption'])
|
||
|
|
self.add_name(figure)
|
||
|
|
return [figure]
|
||
|
|
|
||
|
|
|
||
|
|
class GraphvizSimple(SphinxDirective):
|
||
|
|
"""
|
||
|
|
Directive to insert arbitrary dot markup.
|
||
|
|
"""
|
||
|
|
has_content = True
|
||
|
|
required_arguments = 1
|
||
|
|
optional_arguments = 0
|
||
|
|
final_argument_whitespace = False
|
||
|
|
option_spec: OptionSpec = {
|
||
|
|
'alt': directives.unchanged,
|
||
|
|
'align': align_spec,
|
||
|
|
'caption': directives.unchanged,
|
||
|
|
'layout': directives.unchanged,
|
||
|
|
'graphviz_dot': directives.unchanged, # an old alias of `layout` option
|
||
|
|
'name': directives.unchanged,
|
||
|
|
'class': directives.class_option,
|
||
|
|
}
|
||
|
|
|
||
|
|
def run(self) -> list[Node]:
|
||
|
|
node = graphviz()
|
||
|
|
node['code'] = '%s %s {\n%s\n}\n' % \
|
||
|
|
(self.name, self.arguments[0], '\n'.join(self.content))
|
||
|
|
node['options'] = {'docname': self.env.docname}
|
||
|
|
if 'graphviz_dot' in self.options:
|
||
|
|
node['options']['graphviz_dot'] = self.options['graphviz_dot']
|
||
|
|
if 'layout' in self.options:
|
||
|
|
node['options']['graphviz_dot'] = self.options['layout']
|
||
|
|
if 'alt' in self.options:
|
||
|
|
node['alt'] = self.options['alt']
|
||
|
|
if 'align' in self.options:
|
||
|
|
node['align'] = self.options['align']
|
||
|
|
if 'class' in self.options:
|
||
|
|
node['classes'] = self.options['class']
|
||
|
|
|
||
|
|
if 'caption' not in self.options:
|
||
|
|
self.add_name(node)
|
||
|
|
return [node]
|
||
|
|
else:
|
||
|
|
figure = figure_wrapper(self, node, self.options['caption'])
|
||
|
|
self.add_name(figure)
|
||
|
|
return [figure]
|
||
|
|
|
||
|
|
|
||
|
|
def fix_svg_relative_paths(self: HTML5Translator | LaTeXTranslator | TexinfoTranslator,
|
||
|
|
filepath: str) -> None:
|
||
|
|
"""Change relative links in generated svg files to be relative to imgpath."""
|
||
|
|
tree = ET.parse(filepath) # NoQA: S314
|
||
|
|
root = tree.getroot()
|
||
|
|
ns = {'svg': 'http://www.w3.org/2000/svg', 'xlink': 'http://www.w3.org/1999/xlink'}
|
||
|
|
href_name = '{http://www.w3.org/1999/xlink}href'
|
||
|
|
modified = False
|
||
|
|
|
||
|
|
for element in chain(
|
||
|
|
root.findall('.//svg:image[@xlink:href]', ns),
|
||
|
|
root.findall('.//svg:a[@xlink:href]', ns),
|
||
|
|
):
|
||
|
|
scheme, hostname, rel_uri, query, fragment = urlsplit(element.attrib[href_name])
|
||
|
|
if hostname:
|
||
|
|
# not a relative link
|
||
|
|
continue
|
||
|
|
|
||
|
|
docname = self.builder.env.path2doc(self.document["source"])
|
||
|
|
if docname is None:
|
||
|
|
# This shouldn't happen!
|
||
|
|
continue
|
||
|
|
doc_dir = self.builder.app.outdir.joinpath(docname).resolve().parent
|
||
|
|
|
||
|
|
old_path = doc_dir / rel_uri
|
||
|
|
img_path = doc_dir / self.builder.imgpath
|
||
|
|
new_path = path.relpath(old_path, start=img_path)
|
||
|
|
modified_url = urlunsplit((scheme, hostname, new_path, query, fragment))
|
||
|
|
|
||
|
|
element.set(href_name, modified_url)
|
||
|
|
modified = True
|
||
|
|
|
||
|
|
if modified:
|
||
|
|
tree.write(filepath)
|
||
|
|
|
||
|
|
|
||
|
|
def render_dot(self: HTML5Translator | LaTeXTranslator | TexinfoTranslator,
|
||
|
|
code: str, options: dict, format: str,
|
||
|
|
prefix: str = 'graphviz', filename: str | None = None,
|
||
|
|
) -> tuple[str | None, str | None]:
|
||
|
|
"""Render graphviz code into a PNG or PDF output file."""
|
||
|
|
graphviz_dot = options.get('graphviz_dot', self.builder.config.graphviz_dot)
|
||
|
|
if not graphviz_dot:
|
||
|
|
raise GraphvizError(
|
||
|
|
__('graphviz_dot executable path must be set! %r') % graphviz_dot,
|
||
|
|
)
|
||
|
|
hashkey = (code + str(options) + str(graphviz_dot) +
|
||
|
|
str(self.builder.config.graphviz_dot_args)).encode()
|
||
|
|
|
||
|
|
fname = f'{prefix}-{sha1(hashkey, usedforsecurity=False).hexdigest()}.{format}'
|
||
|
|
relfn = posixpath.join(self.builder.imgpath, fname)
|
||
|
|
outfn = path.join(self.builder.outdir, self.builder.imagedir, fname)
|
||
|
|
|
||
|
|
if path.isfile(outfn):
|
||
|
|
return relfn, outfn
|
||
|
|
|
||
|
|
if (hasattr(self.builder, '_graphviz_warned_dot') and
|
||
|
|
self.builder._graphviz_warned_dot.get(graphviz_dot)):
|
||
|
|
return None, None
|
||
|
|
|
||
|
|
ensuredir(path.dirname(outfn))
|
||
|
|
|
||
|
|
dot_args = [graphviz_dot]
|
||
|
|
dot_args.extend(self.builder.config.graphviz_dot_args)
|
||
|
|
dot_args.extend(['-T' + format, '-o' + outfn])
|
||
|
|
|
||
|
|
docname = options.get('docname', 'index')
|
||
|
|
if filename:
|
||
|
|
cwd = path.dirname(path.join(self.builder.srcdir, filename))
|
||
|
|
else:
|
||
|
|
cwd = path.dirname(path.join(self.builder.srcdir, docname))
|
||
|
|
|
||
|
|
if format == 'png':
|
||
|
|
dot_args.extend(['-Tcmapx', '-o%s.map' % outfn])
|
||
|
|
|
||
|
|
try:
|
||
|
|
ret = subprocess.run(dot_args, input=code.encode(), capture_output=True,
|
||
|
|
cwd=cwd, check=True)
|
||
|
|
except OSError:
|
||
|
|
logger.warning(__('dot command %r cannot be run (needed for graphviz '
|
||
|
|
'output), check the graphviz_dot setting'), graphviz_dot)
|
||
|
|
if not hasattr(self.builder, '_graphviz_warned_dot'):
|
||
|
|
self.builder._graphviz_warned_dot = {} # type: ignore[union-attr]
|
||
|
|
self.builder._graphviz_warned_dot[graphviz_dot] = True
|
||
|
|
return None, None
|
||
|
|
except CalledProcessError as exc:
|
||
|
|
raise GraphvizError(__('dot exited with error:\n[stderr]\n%r\n'
|
||
|
|
'[stdout]\n%r') % (exc.stderr, exc.stdout)) from exc
|
||
|
|
if not path.isfile(outfn):
|
||
|
|
raise GraphvizError(__('dot did not produce an output file:\n[stderr]\n%r\n'
|
||
|
|
'[stdout]\n%r') % (ret.stderr, ret.stdout))
|
||
|
|
|
||
|
|
if format == 'svg':
|
||
|
|
fix_svg_relative_paths(self, outfn)
|
||
|
|
|
||
|
|
return relfn, outfn
|
||
|
|
|
||
|
|
|
||
|
|
def render_dot_html(self: HTML5Translator, node: graphviz, code: str, options: dict,
|
||
|
|
prefix: str = 'graphviz', imgcls: str | None = None,
|
||
|
|
alt: str | None = None, filename: str | None = None,
|
||
|
|
) -> tuple[str, str]:
|
||
|
|
format = self.builder.config.graphviz_output_format
|
||
|
|
try:
|
||
|
|
if format not in ('png', 'svg'):
|
||
|
|
raise GraphvizError(__("graphviz_output_format must be one of 'png', "
|
||
|
|
"'svg', but is %r") % format)
|
||
|
|
fname, outfn = render_dot(self, code, options, format, prefix, filename)
|
||
|
|
except GraphvizError as exc:
|
||
|
|
logger.warning(__('dot code %r: %s'), code, exc)
|
||
|
|
raise nodes.SkipNode from exc
|
||
|
|
|
||
|
|
classes = [imgcls, 'graphviz'] + node.get('classes', [])
|
||
|
|
imgcls = ' '.join(filter(None, classes))
|
||
|
|
|
||
|
|
if fname is None:
|
||
|
|
self.body.append(self.encode(code))
|
||
|
|
else:
|
||
|
|
if alt is None:
|
||
|
|
alt = node.get('alt', self.encode(code).strip())
|
||
|
|
if 'align' in node:
|
||
|
|
self.body.append('<div align="%s" class="align-%s">' %
|
||
|
|
(node['align'], node['align']))
|
||
|
|
if format == 'svg':
|
||
|
|
self.body.append('<div class="graphviz">')
|
||
|
|
self.body.append('<object data="%s" type="image/svg+xml" class="%s">\n' %
|
||
|
|
(fname, imgcls))
|
||
|
|
self.body.append('<p class="warning">%s</p>' % alt)
|
||
|
|
self.body.append('</object></div>\n')
|
||
|
|
else:
|
||
|
|
assert outfn is not None
|
||
|
|
with open(outfn + '.map', encoding='utf-8') as mapfile:
|
||
|
|
imgmap = ClickableMapDefinition(outfn + '.map', mapfile.read(), dot=code)
|
||
|
|
if imgmap.clickable:
|
||
|
|
# has a map
|
||
|
|
self.body.append('<div class="graphviz">')
|
||
|
|
self.body.append('<img src="%s" alt="%s" usemap="#%s" class="%s" />' %
|
||
|
|
(fname, alt, imgmap.id, imgcls))
|
||
|
|
self.body.append('</div>\n')
|
||
|
|
self.body.append(imgmap.generate_clickable_map())
|
||
|
|
else:
|
||
|
|
# nothing in image map
|
||
|
|
self.body.append('<div class="graphviz">')
|
||
|
|
self.body.append('<img src="%s" alt="%s" class="%s" />' %
|
||
|
|
(fname, alt, imgcls))
|
||
|
|
self.body.append('</div>\n')
|
||
|
|
if 'align' in node:
|
||
|
|
self.body.append('</div>\n')
|
||
|
|
|
||
|
|
raise nodes.SkipNode
|
||
|
|
|
||
|
|
|
||
|
|
def html_visit_graphviz(self: HTML5Translator, node: graphviz) -> None:
|
||
|
|
render_dot_html(self, node, node['code'], node['options'], filename=node.get('filename'))
|
||
|
|
|
||
|
|
|
||
|
|
def render_dot_latex(self: LaTeXTranslator, node: graphviz, code: str,
|
||
|
|
options: dict, prefix: str = 'graphviz', filename: str | None = None,
|
||
|
|
) -> None:
|
||
|
|
try:
|
||
|
|
fname, outfn = render_dot(self, code, options, 'pdf', prefix, filename)
|
||
|
|
except GraphvizError as exc:
|
||
|
|
logger.warning(__('dot code %r: %s'), code, exc)
|
||
|
|
raise nodes.SkipNode from exc
|
||
|
|
|
||
|
|
is_inline = self.is_inline(node)
|
||
|
|
|
||
|
|
if not is_inline:
|
||
|
|
pre = ''
|
||
|
|
post = ''
|
||
|
|
if 'align' in node:
|
||
|
|
if node['align'] == 'left':
|
||
|
|
pre = '{'
|
||
|
|
post = r'\hspace*{\fill}}'
|
||
|
|
elif node['align'] == 'right':
|
||
|
|
pre = r'{\hspace*{\fill}'
|
||
|
|
post = '}'
|
||
|
|
elif node['align'] == 'center':
|
||
|
|
pre = r'{\hfill'
|
||
|
|
post = r'\hspace*{\fill}}'
|
||
|
|
self.body.append('\n%s' % pre)
|
||
|
|
|
||
|
|
self.body.append(r'\sphinxincludegraphics[]{%s}' % fname)
|
||
|
|
|
||
|
|
if not is_inline:
|
||
|
|
self.body.append('%s\n' % post)
|
||
|
|
|
||
|
|
raise nodes.SkipNode
|
||
|
|
|
||
|
|
|
||
|
|
def latex_visit_graphviz(self: LaTeXTranslator, node: graphviz) -> None:
|
||
|
|
render_dot_latex(self, node, node['code'], node['options'], filename=node.get('filename'))
|
||
|
|
|
||
|
|
|
||
|
|
def render_dot_texinfo(self: TexinfoTranslator, node: graphviz, code: str,
|
||
|
|
options: dict, prefix: str = 'graphviz') -> None:
|
||
|
|
try:
|
||
|
|
fname, outfn = render_dot(self, code, options, 'png', prefix)
|
||
|
|
except GraphvizError as exc:
|
||
|
|
logger.warning(__('dot code %r: %s'), code, exc)
|
||
|
|
raise nodes.SkipNode from exc
|
||
|
|
if fname is not None:
|
||
|
|
self.body.append('@image{%s,,,[graphviz],png}\n' % fname[:-4])
|
||
|
|
raise nodes.SkipNode
|
||
|
|
|
||
|
|
|
||
|
|
def texinfo_visit_graphviz(self: TexinfoTranslator, node: graphviz) -> None:
|
||
|
|
render_dot_texinfo(self, node, node['code'], node['options'])
|
||
|
|
|
||
|
|
|
||
|
|
def text_visit_graphviz(self: TextTranslator, node: graphviz) -> None:
|
||
|
|
if 'alt' in node.attributes:
|
||
|
|
self.add_text(_('[graph: %s]') % node['alt'])
|
||
|
|
else:
|
||
|
|
self.add_text(_('[graph]'))
|
||
|
|
raise nodes.SkipNode
|
||
|
|
|
||
|
|
|
||
|
|
def man_visit_graphviz(self: ManualPageTranslator, node: graphviz) -> None:
|
||
|
|
if 'alt' in node.attributes:
|
||
|
|
self.body.append(_('[graph: %s]') % node['alt'])
|
||
|
|
else:
|
||
|
|
self.body.append(_('[graph]'))
|
||
|
|
raise nodes.SkipNode
|
||
|
|
|
||
|
|
|
||
|
|
def on_config_inited(_app: Sphinx, config: Config) -> None:
|
||
|
|
css_path = path.join(sphinx.package_dir, 'templates', 'graphviz', 'graphviz.css')
|
||
|
|
config.html_static_path.append(css_path)
|
||
|
|
|
||
|
|
|
||
|
|
def setup(app: Sphinx) -> dict[str, Any]:
|
||
|
|
app.add_node(graphviz,
|
||
|
|
html=(html_visit_graphviz, None),
|
||
|
|
latex=(latex_visit_graphviz, None),
|
||
|
|
texinfo=(texinfo_visit_graphviz, None),
|
||
|
|
text=(text_visit_graphviz, None),
|
||
|
|
man=(man_visit_graphviz, None))
|
||
|
|
app.add_directive('graphviz', Graphviz)
|
||
|
|
app.add_directive('graph', GraphvizSimple)
|
||
|
|
app.add_directive('digraph', GraphvizSimple)
|
||
|
|
app.add_config_value('graphviz_dot', 'dot', 'html')
|
||
|
|
app.add_config_value('graphviz_dot_args', [], 'html')
|
||
|
|
app.add_config_value('graphviz_output_format', 'png', 'html')
|
||
|
|
app.add_css_file('graphviz.css')
|
||
|
|
app.connect('config-inited', on_config_inited)
|
||
|
|
return {'version': sphinx.__display_version__, 'parallel_read_safe': True}
|