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

@@ -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

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

tamer/src/asg/.gitignore

@@ -0,0 +1,4 @@
+
+# generated by tools/asg-ontviz
+ontviz.svg
+

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,

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,

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