]> granicus.if.org Git - graphviz/commit
Migrate output format doc generation ksh to jinja2
authorMark Hansen <mark@markhansen.co.nz>
Sat, 16 May 2020 08:08:12 +0000 (18:08 +1000)
committerMark Hansen <mark@markhansen.co.nz>
Fri, 29 May 2020 12:20:29 +0000 (22:20 +1000)
commit322d1310b9f80dfe625e735d7ce27dc7d80c834c
treea7a142f03f55d9c6eeabb5676f3c96d822e741b5
parentea59e9e6d8dbaf3fc52a4c12102c048f9b6a9985
Migrate output format doc generation ksh to jinja2

This commit replaces the ksh-based templating with Python Jinja2
templating.

Previously output.html was generated with:

- output.1
- the output of mkoutput.sh
- output.2

My end goal here is to make it much simpler to generate more complex
output format docs - however I've made this change so that the output is
virtually unchanged, except for HTML-escaping a single apostrophe.

My plan is to follow this up with adding some more features to the
output format documentation.

Templating in general provides a few opportunities:

- safe auto-html-escaping
- easier editing, easier adding of more data
- some separation of logic and templating
- inclusion of subtemplates

I chose Jinja2 because:

- It's the most popular Python templating engine, used by mature
  products like Ansible and Flask.
- Graphviz's docs generation already takes a dependency on Python for
  jconvert.py.
- The Python language is pretty accessible to contributors.
- Jinja2 seems pretty stable, going back to 2007. Unlikely to break
  soon.

Alternatives considered:
- I could just as well have gone with Go's stdlib template/html but I
  don't think Go is already used to build Graphviz, and Go isn't as
  popular as Python, so not as accessible to contributors.
- Python Django templates: they're pretty similar to Jinja2, but I think
  Django's templates are more heavyweight
doc/info/output.html
doc/infosrc/Makefile
doc/infosrc/mkoutput.py [new file with mode: 0755]
doc/infosrc/mkoutput.sh [deleted file]
doc/infosrc/outputs
doc/infosrc/requirements.txt [new file with mode: 0644]
doc/infosrc/templates/output.html.j2 [new file with mode: 0644]