From a5b03e8790d4eca96b21a3042bf13418b293b4ed Mon Sep 17 00:00:00 2001
From: Mike Gerwitz <mike.gerwitz@ryansg.com>
Date: Fri, 10 Mar 2023 14:11:55 -0500
Subject: [PATCH] tamer: Embed ASG ontology visualization in rustdoc-generated
 docs

There, in-your-face and not hidden in some tools directory.

DEV-13708
---
 tamer/Makefile.am             | 19 ++++++++++++++++---
 tamer/configure.ac            |  3 +++
 tamer/src/asg/.gitignore      |  4 ++++
 tamer/src/asg/graph.rs        |  2 ++
 tamer/src/asg/graph/object.rs |  2 ++
 tamer/src/asg/mod.rs          |  8 ++++++--
 6 files changed, 33 insertions(+), 5 deletions(-)
 create mode 100644 tamer/src/asg/.gitignore

diff --git a/tamer/Makefile.am b/tamer/Makefile.am
index 2e69d127..df22935a 100644
--- a/tamer/Makefile.am
+++ b/tamer/Makefile.am
@@ -25,13 +25,16 @@
 # which is processed by Autoconf into `configure`; they are populated based
 # on the environment in which the `configure` script is invoked.
 
+SHELL = /bin/bash -o pipefail
 .DELETE_ON_ERROR:
 
-.PHONY: all fix fmt check-fmt bench bench-build
+.PHONY: all fix fmt check-fmt bench bench-build FORCE
 
 CARGO_BUILD_FLAGS=@CARGO_BUILD_FLAGS@
 RUSTFLAGS=@RUSTFLAGS@
 
+ontviz_svg := target/doc/tamer/asg/ontviz.svg
+
 .DEFAULT: bin
 
 all: bin doc bench-build
@@ -41,18 +44,28 @@ bin:
 	RUSTFLAGS="$(RUSTFLAGS)" @CARGO@ +@RUST_TC@ @CARGO_FLAGS@ build $(CARGO_BUILD_FLAGS) @FEATURES@
 
 doc: html
-html-am:
+html-am: rustdoc $(ontviz_svg)
+
+.PHONY: rustdoc
+rustdoc:
 	RUSTFLAGS="$(RUSTFLAGS)" @CARGO@ +@RUST_TC@ @CARGO_FLAGS@ test --doc @FEATURES@
 	RUSTFLAGS="$(RUSTFLAGS)" @CARGO@ +@RUST_TC@ @CARGO_FLAGS@ @CARGO_DOC_FLAGS@ doc --document-private-items @FEATURES@
 
+$(ontviz_svg): FORCE
+	tools/asg-ontviz | $(DOT) -Tsvg > $@
+
 # note that 'cargo check' is something else; see 'cargo --help'
 test: check
-check-am: check-lint check-fmt check-cargo check-system
+check-am: check-lint check-fmt check-cargo check-docgen check-system
 
 .PHONY: check-cargo
 check-cargo:
 	RUSTFLAGS="$(RUSTFLAGS)" @CARGO@ +@RUST_TC@ @CARGO_FLAGS@ test --quiet @FEATURES@
 
+.PHONY: check-docgen
+check-docgen:
+	tools/asg-ontviz >/dev/null
+
 .PHONY: check-system
 check-system: bin
 	tests/run-tests
diff --git a/tamer/configure.ac b/tamer/configure.ac
index e9678ad9..55bb7e31 100644
--- a/tamer/configure.ac
+++ b/tamer/configure.ac
@@ -127,6 +127,9 @@ test -z "$FEATURES" || {
 AC_CHECK_PROGS(XMLLINT, [xmllint])
 test -n "$XMLLINT" || AC_MSG_ERROR([xmllint not found])
 
+AC_CHECK_PROGS(DOT, [dot])
+test -n "$DOT" || AC_MSG_ERROR([Graphviz dot not found])
+
 AC_CONFIG_FILES([Makefile conf.sh])
 
 AC_OUTPUT
diff --git a/tamer/src/asg/.gitignore b/tamer/src/asg/.gitignore
new file mode 100644
index 00000000..25315d8e
--- /dev/null
+++ b/tamer/src/asg/.gitignore
@@ -0,0 +1,4 @@
+
+# generated by tools/asg-ontviz
+ontviz.svg
+
diff --git a/tamer/src/asg/graph.rs b/tamer/src/asg/graph.rs
index e9f86ac8..8e4d231c 100644
--- a/tamer/src/asg/graph.rs
+++ b/tamer/src/asg/graph.rs
@@ -18,6 +18,8 @@
 //  along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 //! Abstract semantic graph.
+//!
+//! ![Visualization of ASG ontology](../ontviz.svg)
 
 use self::object::{
     DynObjectRel, ObjectRelFrom, ObjectRelTy, ObjectRelatable, Root,
diff --git a/tamer/src/asg/graph/object.rs b/tamer/src/asg/graph/object.rs
index f8652027..0a21ffa3 100644
--- a/tamer/src/asg/graph/object.rs
+++ b/tamer/src/asg/graph/object.rs
@@ -19,6 +19,8 @@
 
 //! Objects represented by the ASG.
 //!
+//! ![Visualization of ASG ontology](../../ontviz.svg)
+//!
 //! Dynamic Object Types and Narrowing
 //! ==================================
 //! Unlike the functional lowering pipeline that precedes it,
diff --git a/tamer/src/asg/mod.rs b/tamer/src/asg/mod.rs
index dde4bdd9..5dba23a6 100644
--- a/tamer/src/asg/mod.rs
+++ b/tamer/src/asg/mod.rs
@@ -35,8 +35,8 @@
 //!   a linker may choose to use [`crate::global::ProgIdentSize`];
 //!
 //!
-//! Graph Structure
-//! ===============
+//! Graph Ontology
+//! ==============
 //! Each node (vertex) in the graph represents an [`Object`],
 //!   such as an identifier or an expression.
 //! For information on how [`Object`]s are stored and represented on the
@@ -44,6 +44,10 @@
 //!     and for information on relationships between objects,
 //!     see the [`graph::object`] module.
 //!
+//! A visualization of the graph ontology is provided here:
+//!
+//! ![Visualization of ASG ontology](./ontviz.svg)
+//!
 //! Graphs may contain cycles for recursive functions—that is,
 //!   TAME's ASG is _not_ a DAG.
 //! Mutually recursive functions are therefore represented as