docs: Replace ontology class hierarchy ascii art with SVGs

More in line with gi-docgen, generate SVGs for our class hierarchies,
and embed them in the docs.

6 files changed, 163 insertions, 20 deletions

diff --git a/docs/reference/libtracker-sparql/generate-svgs.sh b/docs/reference/libtracker-sparql/generate-svgs.sh
new file mode 100644
index 000000000..c1e15c182
--- /dev/null
+++ b/docs/reference/libtracker-sparql/generate-svgs.sh
@@ -0,0 +1,13 @@
+#!/bin/sh
+command=$1
+docs_path=$2
+
+pushd $docs_path >/dev/null
+
+for i in *.dot
+do
+  filename=`basename -s ".dot" "$i"`
+  $command -Tsvg $i >$filename.svg
+done
+
+popd >/dev/null
diff --git a/docs/reference/libtracker-sparql/meson.build b/docs/reference/libtracker-sparql/meson.build
index 7e987eb54..7c746832d 100644
--- a/docs/reference/libtracker-sparql/meson.build
+++ b/docs/reference/libtracker-sparql/meson.build
@@ -9,6 +9,7 @@ endif
 
 gidocgen_dep = dependency('gi-docgen', fallback: ['gi-docgen', 'dummy_dep'])
 gidocgen = find_program('gi-docgen')
+graphviz_dot = find_program('dot')
 
 ontology_introductions = [
   'nie-introduction.md',
@@ -58,6 +59,16 @@ generated_files = [
   'osinfo-ontology.md.in',
 ]
 
+generate_images = custom_target(
+  'doc-images',
+  output: 'rdfs:Resource-hierarchy.svg',
+  command: [
+    'generate-svgs.sh',
+    graphviz_dot,
+    meson.current_build_dir(),
+  ],
+  depends: [base_ontology_docs, nepomuk_ontology_docs])
+
 generated_targets = []
 generated_content = []
 
@@ -72,7 +83,7 @@ foreach doc : generated_files
       meson.current_build_dir() / doc,
       meson.current_build_dir() / output_file,
     ],
-    depends: [base_ontology_docs, nepomuk_ontology_docs])
+    depends: [base_ontology_docs, nepomuk_ontology_docs, generate_images])
 endforeach
 
 examples = custom_target(
diff --git a/docs/tools/tracker-docgen-md.c b/docs/tools/tracker-docgen-md.c
index abf907cdc..8a1b82ecc 100644
--- a/docs/tools/tracker-docgen-md.c
+++ b/docs/tools/tracker-docgen-md.c
@@ -81,31 +81,18 @@ print_class_hierarchy (FILE                 *f,
                        TrackerOntologyClass *klass,
                        TrackerOntologyModel *model)
 {
-	GPtrArray *strings;
 	const gchar *id;
-	guint i;
 
-	strings = class_get_parent_hierarchy_strings (klass, model);
-
-	if (!strings)
+	if (!klass->superclasses && !klass->subclasses)
+		return;
+	if (g_str_equal (klass->shortname, "nie:InformationElement"))
 		return;
 
 	id = klass->shortname;
-
 	g_fprintf (f, "#### <a name=\"%s.hierarchy\"></a>Class hierarchy\n\n", id);
-	g_fprintf (f, "```\n");
-
-	for (i = 0; i < strings->len; i++) {
-		HierarchyString *str = g_ptr_array_index (strings, i);
-
-		g_fprintf (f, "%s%s%s\n",
-			   str->before->str,
-			   str->class->shortname,
-			   str->after->str);
-	}
-
-	g_fprintf (f, "```\n\n");
-	g_ptr_array_unref (strings);
+	g_fprintf (f, "<div class=\"docblock\">\n");
+	g_fprintf (f, "{{ %s-hierarchy.svg }}\n", id);
+	g_fprintf (f, "</div>\n");
 }
 
 static void
diff --git a/docs/tools/tracker-main.c b/docs/tools/tracker-main.c
index 863b2ab2d..9584ec4ea 100644
--- a/docs/tools/tracker-main.c
+++ b/docs/tools/tracker-main.c
@@ -135,6 +135,8 @@ main (gint argc, gchar **argv)
 			ttl_xml_print (description, model, prefixes[i], output_file, introduction_dir);
 		else if (markdown)
 			ttl_md_print (description, model, prefixes[i], output_file, introduction_dir);
+
+		ttl_generate_dot_files (description, model, prefixes[i], output_file);
 	}
 
 	g_strfreev (prefixes);
diff --git a/docs/tools/tracker-utils.c b/docs/tools/tracker-utils.c
index 498ff4a4a..15eb5f448 100644
--- a/docs/tools/tracker-utils.c
+++ b/docs/tools/tracker-utils.c
@@ -396,3 +396,128 @@ class_get_parent_hierarchy_strings (TrackerOntologyClass *klass,
 
 	return strings;
 }
+
+static gchar *
+link_from_shortname (const gchar *shortname)
+{
+	const gchar *sep;
+	gchar *link, *prefix;
+
+	sep = strstr (shortname, ":");
+	g_assert (sep != NULL);
+
+	prefix = g_strndup (shortname, sep - shortname);
+	link = g_strdup_printf ("%s-ontology.html#%s", prefix, shortname);
+	g_free (prefix);
+
+	return link;
+}
+
+static void
+describe_class (FILE                 *f,
+                TrackerOntologyModel *model,
+                TrackerOntologyClass *klass,
+                gboolean              link)
+{
+	g_fprintf (f, "node [shape=\"box\", style=\"rounded\", border=\"0\", fontname=\"sans-serif\"");
+
+	if (link) {
+		g_autofree gchar *link = NULL;
+
+		link = link_from_shortname (klass->shortname);
+		g_fprintf (f, ", class=\"link\", href=\"%s\"", link);
+	}
+
+	g_fprintf (f, "]; \"%s\"\n", klass->shortname);
+}
+
+static void
+print_superclasses (FILE                 *f,
+                    TrackerOntologyModel *model,
+                    TrackerOntologyClass *klass,
+                    GHashTable           *visited,
+                    gboolean              link)
+{
+	GList *l;
+
+	if (g_hash_table_contains (visited, klass))
+	    return;
+
+	describe_class (f, model, klass, link);
+
+	for (l = klass->superclasses; l; l = l->next) {
+		TrackerOntologyClass *superclass;
+
+		superclass = tracker_ontology_model_get_class (model, l->data);
+		print_superclasses (f, model, superclass, visited, TRUE);
+		g_fprintf (f, "\"%s\" -- \"%s\"\n", superclass->shortname, klass->shortname);
+	}
+
+	g_hash_table_add (visited, klass);
+}
+
+static void
+ttl_generate_class_hierarchy_dot (TrackerOntologyDescription *description,
+                                  TrackerOntologyModel       *model,
+                                  TrackerOntologyClass       *klass,
+                                  GFile                      *output_location)
+{
+	gchar *path, *filename;
+	GFile *file;
+	g_autoptr(GHashTable) visited = NULL;
+	FILE *f;
+	GList *l;
+
+	if (!klass->subclasses && !klass->superclasses)
+		return;
+
+	filename = g_strdup_printf ("%s-hierarchy.dot", klass->shortname);
+	file = g_file_get_child (output_location, filename);
+	g_free (filename);
+
+	path = g_file_get_path (file);
+	f = fopen (path, "w");
+	g_assert (f != NULL);
+	g_free (path);
+
+	g_fprintf (f, "graph G {\n");
+	g_fprintf (f, "bgcolor=\"transparent\";\n");
+	g_fprintf (f, "rankdir=TB;\n");
+
+	visited = g_hash_table_new (NULL, NULL);
+
+	print_superclasses (f, model, klass, visited, FALSE);
+
+	for (l = klass->subclasses; l; l = l->next) {
+		TrackerOntologyClass *subclass;
+
+		subclass = tracker_ontology_model_get_class (model, l->data);
+		describe_class (f, model, subclass, TRUE);
+		g_fprintf (f, "\"%s\" -- \"%s\"\n", klass->shortname, subclass->shortname);
+	}
+
+	g_fprintf (f, "}");
+
+	g_object_unref (file);
+	fclose (f);
+}
+
+void
+ttl_generate_dot_files (TrackerOntologyDescription *description,
+                        TrackerOntologyModel       *model,
+                        const gchar                *prefix,
+                        GFile                      *output_location)
+{
+	g_autoptr(GList) classes = NULL;
+	GList *l;
+
+	classes = tracker_ontology_model_list_classes (model, prefix);
+
+	for (l = classes; l; l = l->next) {
+		TrackerOntologyClass *klass;
+
+		klass = tracker_ontology_model_get_class (model, l->data);
+
+		ttl_generate_class_hierarchy_dot (description, model, klass, output_location);
+	}
+}
diff --git a/docs/tools/tracker-utils.h b/docs/tools/tracker-utils.h
index 8a9eb2c17..f2e8e00e9 100644
--- a/docs/tools/tracker-utils.h
+++ b/docs/tools/tracker-utils.h
@@ -39,6 +39,11 @@ GPtrArray *
 class_get_parent_hierarchy_strings (TrackerOntologyClass *klass,
                                     TrackerOntologyModel *model);
 
+void ttl_generate_dot_files (TrackerOntologyDescription *description,
+                             TrackerOntologyModel       *model,
+                             const gchar                *prefix,
+                             GFile                      *output_location);
+
 G_END_DECLS
 
 #endif /* TRACKER_UTILS_H */