Put graphviz objects into a zoom & pan box.

[Paebbels]

Feature Description

Diagrams generated with embedded Graphviz code or read dot files may be quite large. Zooming and panning will help to navigate in big diagrams. The sphinx.ext.graphviz extension generates diagrams as SVG graphics. SVG graphics are displayed with an object tag in HTML.

Describe the solution you'd like

Added a zoom and pan functionality is quite simple. E.g. the svg-pan-zoom framework could solve it with a few lines of Javascript code:

<object id="demo-tiger" type="image/svg+xml" data="tiger.svg" style="width: 500px; height: 500px; border:1px solid black; ">Your browser does not support SVG</object>

<script>
document.getElementById('my-embed').addEventListener('load', function(){
  // Will get called after embed element was loaded
  svgPanZoom(document.getElementById('my-embed'));
})
</script>

Describe alternatives you've considered There are other Javascript based frameworks offering such a option.

Additional context

This could also be useful with:

• sphinx.ext.inheritance_diagram

---

/cc: @eine

[tk0miya]

I think Sphinx already provides enough APIs and hooks. So we can make such extension. So -1 for adding it to core.

[Paebbels]

@tk0miya arn't all extensions in namespace sphinx.ext.* part of Sphinx? Thus it's core, right?

[tk0miya]

Yes. I meant I'd not like to add zoom feature to sphinx package. Please add it as your own extension. I suppose you can do it with app.add_js_file() API.

[Paebbels]

This will add the JS file, but it doesn't edit the HTML template.

I don't think it's good to create so many variations of Sphinx.
To create a modified extension I need to:

• manually copy the code for sphinx.ext.graphviz
• patch the code
• create a Git repository for that extension
• create a PyPI package description
• create a CI flow to package and deliver packages to PyPI
• adjust my requirements.txt and conf.py to use the new package name

Other drawbacks:

• if Sphinx updates the original code, it can not be updated in the modified extension via e.g. Git features
  => needs again manual copying and patching
• I occupy more names in the limited namespace of PyPI

---

Adding zooming to Sphinx code base could mean:

• reuse of such a JS framework in many places using SVG graphics:
  • inheritance_diagrams
  • graphviz
  • image
  • ...
• adding an option to give users a choice if zooming should be enabled.
  e.g. :zoomable:

If you prefer users to create hundreds of modified extension versions, you you consider two options:

• a better way to patch Sphinx standard packages from conf.py or similar
• offer Sphinx as a namespace packages. Thus each part of Sphinx is one package forming an overall namespace. Each PyPI namespace package would be one Git repository, that can be forked and patched.

[tk0miya]

TBH, Sphinx project does not have enough resource to maintain Sphinx core. There are still many issues and PRs. So I'd not like to add more new minor feature to Sphinx. I don't think zooming is important feature for all documents. So it is better to implement this as an extension.

In addition, zooming feature is available only in HTML format, right? One of the concept of Sphinx is "one source, multiple output". So I feel strange to add :zoomable: to SVG images. I also afraid adding it to HTML writer causes their children broken (EPUB, HTMLhelp and so on).

I'm ready to add new APIs and libraries if you feel Sphinx is not extensible. What is shortage to realize zooming?

[Paebbels]

If you want to split and distribute work, would it be good to move Sphinx extensions to separate packages or to sphinxcontrib ?

I'm aware of the shortcomings of zooming being HTML-only. Currently, I have no idea for other format. In LaTeX an inner double-page could be use to have a landscape A3 format ... but this is complicated and very specific too ...

On the other hand, many people document sourcecode and big projects with:

• Sphinx + ReadTheDocs
• Sphinx + GH Pages (using Travis or GH Actions)
• Sphinx + GL Pages (using Travis or GH Actions)

These projects mainly need HTML results.

My use cases for bigger SVG images are:

• UML like diagrams
• State machine diagrams

SVG has the ability to be perfectly zoomable.

Example: The following state machine is only drawn by 20%.

[Paebbels]

@tk0miya where can I ask further questions regarding the graphviz extension?

Based on Sphinx 2.3.1.

• Option :name: in Graphviz(SphinxDirective) is not used by the extension. According to the documentation it sets the label of the graph, but option_spec = {..., 'name': directives.unchanged, ...} no nowhere referenced again.
  Actually, the diagram name seem to be used from :caption::

  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]

• The same is true for GraphvizSimple(SphinxDirective)
• Checking further, the documentation lists an option called :class:, but it's not allowed for neither directive:

  option_spec = {
  '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,
  }

• In directive Graphviz, option :graphviz_dot: is deprecated and replaced by option :layout:. This change was not applied to directive GraphvizSimple. Move over, the documentation lists the same options for both directives, but according to the code it's not correct.
• According to you comment above, I added:

  app.add_js_file('svg-pan-zoom.min.js')

  How does add_js_file find my Javascript file in my repository?

  btd/
  sphinx/
    graphviz.py
  svg-pan-zoom/
  svg-pan-zoom.min.js
  setup.py

• I need to add a unique ID to each <object ...> in HTML. This ID is later referenced by a <script ...> tag to connect the Javascript framework to the SVG instance.
  • Where can I add an ID generator (counter) that has a HTML file scope. IDs don't need to be global for the whole documentation.

[Paebbels]

@tk0miya I have made a forked version of the graphviz extension (see: https://github.com/buildthedocs/sphinx.graphviz)
More over I also needed to fork inheritance_diagram (see https://github.com/buildthedocs/sphinx.inheritance_diagram)

Can you please assist and answer the questions above or should I report some of them as a bug?