From: Mark Hansen <markhansen@google.com>
Date: Sun, 28 Feb 2021 09:51:14 +0000 (+1100)
Subject: Adapt mkoutput.py to generate YAML for jekyll
X-Git-Tag: 2.47.0~29^2
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=7d5a4f3cec828227d1e88a53a0a2d06235426204;p=graphviz

Adapt mkoutput.py to generate YAML for jekyll

This is towards #1962. The output yaml-front-matter HTML can be used as input to jekyll.
---

diff --git a/doc/infosrc/Makefile b/doc/infosrc/Makefile
index 0f21dfb2d..aa0994515 100644
--- a/doc/infosrc/Makefile
+++ b/doc/infosrc/Makefile
@@ -11,15 +11,12 @@
 #  python is used to run:
 #  - jconvert.py, which converts the json schema graphviz_json_schema.json to html.
 #    This also relies on the python package json2html.
-#  - mkoutput.py, which converts templates/output.html.j2 to output.html
-#    This requires the jinja2 python package.
 #
 # The main products are web pages:
 #    arrows.html  - arrow_grammar
 #    colors.html  - color_names svgcolor_names brewer_colors
 #    command.html - raw HTML
 #    lang.html    - grammar
-#    output.html  - outputs
 #    shapes.html  - shapelist, html_grammar
 #
 # The files listed after each give the main data files used to
@@ -86,7 +83,7 @@ A2GIF= aa_box.gif aa_lbox.gif aa_rbox.gif aa_obox.gif aa_olbox.gif aa_orbox.gif\
 
 GIF = $(SGIF) $(AGIF) $(MGIF) $(A2GIF) $(XGIF)
 DOTS = html2.gv html3.gv html4.gv tee.gv
-HTML = colors.html command.html lang.html output.html shapes.html \
+HTML = colors.html command.html lang.html shapes.html \
        arrows.html schema.html
 MISC = graphviz_json_schema.json w3data.js
 INSTALL_FILES = $(HTML) $(DOTS) $(SGIF) $(AGIF) $(A2GIF) $(MGIF) $(XGIF) $(MPNG) $(MISC)
@@ -133,9 +130,6 @@ colors.html : colors.1 colors.n ../../lib/common/color_names ../../lib/common/sv
 	rm -rf colortmp
 
 
-output.html : outputs mkoutput.py plugins.png schema.html templates/output.html.j2
-	./mkoutput.py < outputs > output.html
-
 schema.html : jconvert.py graphviz_json_schema.json
 	./jconvert.py graphviz_json_schema.json schema.html
 
@@ -202,17 +196,17 @@ clean :
 
 .PHONY: distclean
 distclean : clean
-	rm -f colors.html output.html shapes.html lang.html arrows.html schema.html
+	rm -f colors.html shapes.html lang.html arrows.html schema.html
 	rm -f $(A2GIF) $(AGIF) $(SGIF) $(MPJG) $(MGIF) $(MPNG) $(XGIF) shapes
 	(for s in $$(cat shapelist); do rm -f $$s.gif; done)
 
 EXTRA_DIST = $(XGIF) mklang.y mkarrows.sh mkshapes.sh mkstyles.sh mktapers.sh \
-             mkarrowtbl.sh mkoutput.py mkshhtml.py \
+             mkarrowtbl.sh mkshhtml.py \
 	           ps_to_png.sh arrow_grammar grammar html_grammar \
              shapelist colors.1 colors.n \
-             output.1 output.2 html.1 html.2 html1.dot html.3 \
+             html.1 html.2 html1.dot html.3 \
              shapes.1 shapes.2 shapes.3 lang.1 lang.2 arrows.1 arrows.2 \
              brewer.awk mkcolors.awk svg.awk sz.awk \
              colorlist.dot html1.dot html4.dot round.dot constraint.dot \
              html2.dot mrecord.dot sdlshapes.dot fill.dot html3.dot record.dot \
-             X11 outputs eqn.gif plugins.gv
+             X11 eqn.gif plugins.gv
diff --git a/doc/infosrc/mkoutput.py b/doc/infosrc/mkoutput.py
index f6eb25a67..72c5292ba 100755
--- a/doc/infosrc/mkoutput.py
+++ b/doc/infosrc/mkoutput.py
@@ -1,24 +1,23 @@
 #!/usr/bin/env python3
-# Takes `outputs` as stdin and generates output.html
-# Uses `templates/output.html.j2`
-# See `outputs` file for format documentation.
 
-import markupsafe
 import re
 import sys
-from typing import Dict, Tuple
-import templates
+from typing import List
+from dataclasses import dataclass, asdict
+import yaml
+
+@dataclass
+class Output:
+    # List of command-line-params for an output format, e.g. ('jpg', 'jpeg', 'jpe')
+    params: List[str]
+    # Full name of the output format
+    name: str
+    # HTML description string
+    html_description: str
 
 HEADER_RE = re.compile(r'^:(?P<params>[^:]+):(?P<format>.*)')
 
-# Tuple of command-line-params for an output format, e.g. ('jpg', 'jpeg', 'jpe')
-params : Tuple[str, ...] = ()
-
-# Map from tuple of command-line-params to full name of the output format
-formats : Dict[Tuple[str, ...], str] = {}
-
-# Map from tuple of command-line-params to an HTML description string
-html_descriptions : Dict[Tuple[str, ...], str]  = {}
+outputs : List[Output] = []
 
 for line in sys.stdin:
     # Skip comment lines.
@@ -28,27 +27,28 @@ for line in sys.stdin:
     m = HEADER_RE.match(line)
     if m:
         # This is a header line. Grab out the values.
+        outputs.append(Output(
+            # Command-line formats are slash-separated.
+            params = m.group('params').split('/'),
+            # Full format name is plain text
+            name = m.group('format'),
+            # Set an empty string html description, ready to append to.
+            html_description = '',
+        ))
 
-        # Command-line formats are slash-separated.
-        params = tuple(m.group('params').split('/'))
-
-        # Full format name is plain text
-        formats[params] = m.group('format')
-
-        # Set an empty string html description, ready to append to.
-        html_descriptions[params] = ''
     else:
         # This is an HTML line, possibly a continuation of a previous HTML line.
-        html_descriptions[params] += line
-
-
-template = templates.env().get_template('output.html.j2')
-print(template.render(
-    formats=formats,
-    # Vouch for the HTML descriptions as being safe and not needing auto-HTML-escaping.
-    # This is reasonable because the HTML descriptions are not attacker-controlled.
-    descriptions={
-        params: markupsafe.Markup(desc)
-        for params, desc in html_descriptions.items()
-    }
-))
+        outputs[-1].html_description += line
+
+
+for o in outputs:
+    filename = o.params[0]
+    with open("_formats/" + filename + ".html", 'w') as f:
+        html_description = o.html_description
+        d = asdict(o)
+        del d["html_description"]
+
+        print("---", file=f)
+        print(yaml.dump(d), end='', file=f)
+        print("---", file=f)
+        print(html_description, end='', file=f)
diff --git a/doc/infosrc/templates/output.html.j2 b/doc/infosrc/templates/output.html.j2
deleted file mode 100644
index 351f8708a..000000000
--- a/doc/infosrc/templates/output.html.j2
+++ /dev/null
@@ -1,98 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
-<!--
-    This is a generated document.  Do not edit.
--->
-<HTML VERSION="2.0">
-<HEAD>
-<TITLE>Output Formats</TITLE>
-<style>
-.jsontable {
-    border: 1px solid black;
-    background-color: beige;
-}
-</style>
-<script src="w3data.js"></script>
-</HEAD>
-<BODY BGCOLOR=white>
-<A NAME="top"></A>
-<H1 align=CENTER>Output Formats</H1>
-<HR>
-The output format is specified with the <STRONG>-T</STRONG><I>lang</I>
-flag on the <A HREF=command.html>command line</A>, where <I>lang</I>
-is one of the parameters listed below.
-<P>
-The formats actually available in a given Graphviz system depend on
-how the system was built and the presence of additional libraries.
-To see what formats <b>dot</b> supports, run <TT>dot -T?</TT>.
-See the <A HREF=command.html#d:T> description of the -T</A>
-flag for additional information.
-<P>
-Note that the internal coordinate system has the origin
-in the lower left corner.
-Thus, positions in the
-<A HREF=#d:canon>canon</A>,
-<A HREF=#d:dot>dot</A>,
-<A HREF=#d:xdot>xdot</A>,
-<A HREF=#d:plain>plain</A>, and
-<A HREF=#d:plain-ext>plain-ext</A>
-formats need to be interpreted in this manner.
-<P>
-<TABLE ALIGN=CENTER>
-<TR><TH>Command-line<BR>parameter</TH><TH>Format</TH></TR>
-{% for params, format in formats | dictsort %}
- <TR><TD ALIGN=CENTER>
-  {%- for p in params -%}
-    <A NAME=a:{{p}} HREF=#d:{{p}}>{{p}}</A>
-    {%- if not loop.last %}
-
-<BR>
-    {%- endif %}
-  {%- endfor %}
-
-</TD><TD>{{ format }}</TD> </TR>
-{% endfor %}
-</TABLE>
-<HR>
-<H2>Format Descriptions</H2>
-<DL>
-{% for params, description in descriptions | dictsort %}
-  {% for p in params %}
-    {% if not loop.first -%}
-      ,
-    {%- endif -%}
-    <DT><A NAME=d:{{p}} HREF=#a:{{p}}><STRONG>{{p}}</STRONG></A>
-  {% endfor -%}
-  <DD>
-  {{- description }}
-{% endfor %}
-</DL>
-<HR>
-<H1 align=CENTER><A NAME=d:image_fmts>Image Formats</A></H1>
-<HR>
-The <A HREF=attrs.html#a:image>image</A> and <A HREF=attrs.html#a:shapefile>shapefile</A> attributes specify an image file to be included
-as part of the final diagram. Not all image formats can be read. In addition,
-even if read, not all image formats can necessarily be used in a given
-output format.
-<P>
-The graph below shows what image formats can be used in which output formats,
-and the required plugins. On the left are the supported image formats. 
-On the right are the supported output formats.
-In the middle are the plugins: image loaders, renderers, drivers, arranged by 
-plugin library.  
-This presents the most general case. A given installation may not provide
-one of the plugins, in which case, that transformation is not possible.
-<BR>
-<IMG WIDTH="80%" SRC="plugins.png">
-<HR>
-<H2>Notes</H2>
-<OL TYPE="1">
-<LI>
-<A NAME=ID></A>In the formats: -Tcmap, -Tcmapx, -Tsvg, -Tvml, the output generates
-'id="node#"' properties for nodes, 'id="edge#"' properties for edges, and 'id="cluster#"' properties for clusters, with the '#' replaced by an internally assigned integer. These strings can be provided instead by an externally provided "id=xxx" attribute on the object.
-Normal "&#92;N" "&#92;E" "&#92;G" substitutions are applied.
-Externally provided id values are not used internally, and it is the use's reponsibilty to ensure
-that they are sufficiently unique for their intended downstream use.
-Note, in particular, that "&#92;E" is not a unique id for multiedges.
-</OL>
-</BODY>
-</HTML>