doc: Switch from static image files to generated diagrams.

Switches diagrams from using static PNG images to instead generate them via
simple graphviz DOT markup files.

Signed-off-by: Jon A. Cruz <jonc@osg.samsung.com>

configure.ac

@@ -27,6 +27,7 @@ AM_SILENT_RULES([yes])
 # Check for programs
 AC_PROG_CC
 AC_PROG_CXX
+AC_PROG_GREP
 
 # check if we have C++ compiler. This is hacky workaround,
 # for a reason why it is this way see
@@ -135,6 +136,18 @@ if test "x$enable_documentation" = "xyes"; then
 		AC_MSG_ERROR([Documentation build requested but xmlto not found. Install xmlto or disable the documentation using --disable-documentation])
 	fi
 
+	AC_PATH_PROG(DOT, dot)
+	if test "x$DOT" = "x"; then
+		AC_MSG_ERROR([Documentation build requested but graphviz's dot not found. Install graphviz or disable the documentation using --disable-documentation])
+	fi
+	AC_MSG_CHECKING([for compatible dot version])
+	dot_version=`$DOT -V 2>&1|$GREP -oP '(?<=version\W)@<:@0-9.@:>@*(?=\W(.*))'`
+	AS_VERSION_COMPARE([$dot_version], [2.26.0],
+	                   [AC_MSG_RESULT([no])
+	                    AC_MSG_ERROR([Graphviz dot $dot_version too old. Graphviz 2.26+ required for documentation build. Install required graphviz version or disable the documentation using --disable-documentation])],
+	                   [AC_MSG_RESULT([yes])],
+	                   [AC_MSG_RESULT([yes])])
+
 	AC_CONFIG_FILES([
 	doc/doxygen/wayland.doxygen
 	])

doc/doxygen/Makefile.am

@@ -1,4 +1,6 @@
 
+.SUFFIXES = .gv .png
+
 noinst_DATA = xml/Client/index.xml xml/Server/index.xml
 dist_noinst_DATA = wayland.doxygen.in
 
@@ -22,15 +24,21 @@ scanned_src_files_man =					\
 	$(top_srcdir)/src/wayland-client.c	\
 	$(top_srcdir)/src/wayland-client.h
 
+diagramsdir := dot
+diagramssrc := $(wildcard $(diagramsdir)/*.gv)
+diagrams := $(patsubst $(diagramsdir)/%,xml/%,$(diagramssrc:.gv=.png))
+
 # find all man/man3/wl_foo.3 pages
 # for this to work, we need to create them before the man target (hence
 # all-local below)
 dist_man3_MANS = $(shell test -d man && find man/man3 -name "wl_*.3" -printf "man/man3/%P\n")
 
 # Listing various directories that might need to be created.
-alldirs := xml/Client xml/Server man/man3
+alldirs := xml xml/Client xml/Server man/man3
 
-xml/%/index.xml: $(scanned_src_files_%) wayland.doxygen | xml/%
+$(diagrams): $(diagramssrc)
+
+xml/%/index.xml: $(scanned_src_files_%) wayland.doxygen $(diagrams) | xml/%
 	$(AM_V_GEN)(cat wayland.doxygen; \
           echo "GENERATE_XML=YES"; \
           echo "XML_OUTPUT=xml/$*"; \
@@ -45,6 +53,9 @@ man/man3/wl_display.3: $(scanned_src_files_man) wayland.doxygen | man/man3
           echo "INPUT= $(scanned_src_files_man)"; \
           ) | $(DOXYGEN) -
 
+xml/%.png: $(diagramsdir)/%.gv | xml
+	$(AM_V_GEN)$(DOT) -Tpng -o$@ $<
+
 # general rule to create one of the listed directories.
 $(alldirs):
 	$(AM_V_GEN)$(MKDIR_P) $@

doc/doxygen/dot/wayland-architecture.gv

@@ -0,0 +1,39 @@
+digraph arch_wayland {
+    edge[
+        fontname="DejaVu Sans";
+        dir="both";
+        arrowtail="dot";
+        arrowsize=.5;
+        fontname="DejaVu Sans"
+        fontsize="18";
+    ]
+
+    node[
+        shape="Mrecord";
+        color=none;
+        fillcolor="#ffbc00";
+        style="filled";
+        fontname="DejaVu Sans"
+        fontsize="18";
+   ]
+
+    c1 [label="Wayland Client"; URL="#c1"]
+    c2 [label="Wayland Client"; URL="#c2"]
+
+    comp [tooltip="Wayland Compositor" label="|{|Wayland\nCompositor|}|"; URL="#comp"]
+
+    impl [tooltip="KMS evdev Kernel" label="|{{KMS|evdev}|Kernel}|"; URL="#impl"]
+
+
+    c1 -> comp [taillabel="③"; labeldistance=2.5; URL="#step_3"];
+    c2 -> comp;
+
+    comp -> c1 [label="②"; URL="#step_2"];
+    comp -> c2;
+
+    comp -> impl [xlabel = "④"; URL="#step_4"];
+    comp -> impl [style = invis; label="    "];
+    impl -> comp [xlabel = "①"; URL="#step_1"];
+
+    c1 -> c2 [style=invis];
+ }

doc/doxygen/dot/x-architecture.gv

@@ -0,0 +1,54 @@
+digraph arch_x {
+    edge[
+        fontname="DejaVu Sans";
+        dir="both";
+        arrowtail="dot";
+        arrowsize=.5;
+        fontname="DejaVu Sans"
+        fontsize="18";
+    ]
+
+    node[
+        shape="Mrecord";
+        color=none;
+        fillcolor="#ffbc00";
+        style="filled";
+        fontname="DejaVu Sans"
+        fontsize="18";
+    ]
+
+    {
+        rank=same;
+        c1 [label="X Client"; URL="#c1"]
+        c3 [label="X Client"; URL="#c3"]
+    }
+    c2 [label="X Client"; URL="#c2"]
+
+    {
+        rank=same;
+        xserver [tooltip="X Server" label="|{|X Server|}|"; URL="#xserver"]
+        comp [tooltip="Compositor" label="|{|Compositor|}|"; URL="#comp"]
+    }
+
+    impl [tooltip="KMS evdev Kernel" label="|{{KMS|evdev}|Kernel}|"; URL="#impl"]
+
+    c1 -> xserver [taillabel="③"; labeldistance=2; URL="#step_3"];
+    c2 -> xserver;
+    c3 -> xserver;
+
+    xserver -> c1 [taillabel="②"; labeldistance=2; URL="#step_2"];
+    xserver -> c2;
+    xserver -> c3;
+
+    xserver -> impl [taillabel = "⑥"; labeldistance=1.75; URL="#step_6"];
+    xserver -> impl [style = invis; label="    "];
+    impl -> xserver [taillabel = "①"; labeldistance=1.75; URL="#step_1"];
+
+    xserver -> comp [style=invis];
+    xserver -> comp [taillabel="④"; labeldistance=1.75; labelangle=-45; URL="#step_4"];
+    comp -> xserver [taillabel="⑤"; URL="#step_5"];
+    comp -> xserver [style=invis]
+
+    c1 -> c2 [style=invis];
+    c3 -> c2 [style=invis];
+ }

doc/publican/Makefile.am

@@ -12,6 +12,9 @@
 #   $(builddir)/en-US
 # * run xmlto on $(builddir)/en-US, output to $(builddir)/Wayland/en-US
 
+doxydir := $(top_builddir)/doc/doxygen
+html_destdir := $(builddir)/Wayland/en-US/html
+
 publican_sources = \
 	$(srcdir)/sources/Wayland.ent \
 	$(srcdir)/sources/Wayland.xml \
@@ -25,9 +28,7 @@ publican_sources = \
 	$(srcdir)/sources/Protocol.xml \
 	$(srcdir)/sources/Compositors.xml \
 	$(srcdir)/sources/images/icon.svg  \
-	$(srcdir)/sources/images/wayland-architecture.png \
+	$(srcdir)/sources/images/wayland.png
-	$(srcdir)/sources/images/wayland.png  \
-	$(srcdir)/sources/images/x-architecture.png
 
 css_sources = \
 	$(srcdir)/sources/css/brand.css \
@@ -38,9 +39,11 @@ css_sources = \
 
 img_sources = \
 	$(srcdir)/sources/images/icon.svg \
-	$(srcdir)/sources/images/wayland-architecture.png \
+	$(srcdir)/sources/images/wayland.png
-	$(srcdir)/sources/images/wayland.png \
+
-	$(srcdir)/sources/images/x-architecture.png
+doxygen_img_sources := \
+	$(doxydir)/xml/wayland-architecture.png \
+	$(doxydir)/xml/x-architecture.png
 
 if HAVE_XMLTO
 if HAVE_XSLTPROC
@@ -51,18 +54,15 @@ XMLTO_PARAM = \
 	--stringparam toc.section.depth=1 \
 	--stringparam html.stylesheet=css/default.css
 
-doxydir := $(top_builddir)/doc/doxygen
-
-html_destdir = $(builddir)/Wayland/en-US/html
-
 # Listing various directories that might need to be created.
 alldirs := $(builddir)/en-US $(builddir)/en-US/images $(html_destdir) $(html_destdir)/css $(html_destdir)/images
 
 
 html_css_targets = $(addprefix $(html_destdir)/css/,$(notdir $(css_sources)))
 html_img_targets = $(addprefix $(html_destdir)/images/,$(notdir $(img_sources)))
+doxygen_img_targets := $(doxygen_img_sources:$(doxydir)/xml/%=$(html_destdir)/images/%)
 
-$(builddir)/Wayland: $(publican_targets) $(html_css_targets) $(html_img_targets) | $(builddir)/en-US
+$(builddir)/Wayland: $(publican_targets) $(html_css_targets) $(html_img_targets) $(doxygen_img_targets) | $(builddir)/en-US
 	$(AM_V_GEN)$(XMLTO) $(XMLTO_PARAM) html $(builddir)/en-US/Wayland.xml -o $(html_destdir)
 	@touch $@
 
@@ -72,6 +72,9 @@ $(html_destdir)/css/%: $(srcdir)/sources/css/% | $(html_destdir)/css
 $(html_destdir)/images/%: $(srcdir)/sources/images/% | $(html_destdir)/images
 	$(AM_V_GEN)cp -f $< $@
 
+$(html_destdir)/images/%: $(doxydir)/xml/% | $(html_destdir)/images
+	$(AM_V_GEN)cp -f $< $@
+
 pubdir = $(docdir)/Wayland/en-US
 
 publican_targets = $(publican_sources:$(srcdir)/sources/%=$(builddir)/en-US/%) \
@@ -104,6 +107,10 @@ $(builddir)/en-US/%: $(srcdir)/sources/% $(publican_sources) | $(builddir)/en-US
 	$(AM_V_GEN)cp -f $< $@
 	$(AM_V_at)chmod a+w $@
 
+$(builddir)/en-US/images/%: $(doxydir)/xml/% | $(builddir)/en-US/images
+	$(AM_V_GEN)cp -f $< $@
+	$(AM_V_at)chmod a+w $@
+
 # general rule to create one of the listed directories.
 $(alldirs):
 	$(AM_V_GEN)$(MKDIR_P) $@