docs: Generate reference manual with gi-docgen

4 files changed, 362 insertions, 86 deletions

diff --git a/docs/reference/libtracker-sparql/meson.build b/docs/reference/libtracker-sparql/meson.build
index cc9c793a9..e30f0fad1 100644
--- a/docs/reference/libtracker-sparql/meson.build
+++ b/docs/reference/libtracker-sparql/meson.build
@@ -1,67 +1,33 @@
-version_xml = configure_file(input: 'version.xml.in',
-    output: 'version.xml',
-    configuration: conf)
-
-generated = custom_target('base-ontology-doc-generated',
-    output: 'gen-doc.stamp',
-    command: [ttl2xml,
-              '-d', join_paths(source_root, 'src/ontologies/'),
-              '-o', join_paths(meson.current_build_dir(), 'xml/'),
-              '-e', meson.current_source_dir()],
-    depends: ttl2xml,
-    depend_files: base_ontology,
-    build_by_default: true,
-)
-
-example_files = [
-    'examples/ontologies/defining-cardinality-1.rq', 'examples/ontologies/defining-cardinality-2.txt',
-    'examples/ontologies/defining-cardinality-3.rq', 'examples/ontologies/defining-classes-1.txt',
-    'examples/ontologies/defining-classes-2.txt', 'examples/ontologies/defining-classes-3.rq',
-    'examples/ontologies/defining-fts-indexes-1.txt', 'examples/ontologies/defining-fts-indexes-2.rq',
-    'examples/ontologies/defining-indexes-1.txt', 'examples/ontologies/defining-namespaces-1.txt',
-    'examples/ontologies/defining-properties-1.txt', 'examples/ontologies/defining-properties-2.txt',
-    'examples/ontologies/defining-properties-3.txt', 'examples/ontologies/defining-properties-4.rq',
-    'examples/ontologies/defining-uniqueness-1.txt', 'examples/ontologies/defining-uniqueness-2.rq',
-    'examples/ontologies/example.description', 'examples/ontologies/predefined-elements-1.txt',
-    'examples/ontologies/predefined-elements-2.rq',
-    'examples/readonly-example.c', 'examples/writeonly-example.c',
-    'examples/writeonly-with-blank-nodes-example.c',
+content = [
+  'tutorial.md',
 ]
 
-image_files = [
-    'images/triple-graph-1.png',
-    'images/triple-graph-2.png',
-    'images/triple-graph-3.png',
-]
-
-private_headers = [
-    'tracker-notifier-private.h',
-    'tracker-private.h',
-    'tracker-serializer.h',
-    'tracker-serializer-json.h',
-    'tracker-serializer-xml.h',
-    'direct',
-    'bus',
-    'remote',
-]
+# The TOML gi-docgen configuration wants a list of quoted file names.
+_quoted = []
+foreach c : content
+  _quoted += '"@0@"'.format(c)
+endforeach
 
-gnome.gtkdoc('libtracker-sparql',
-    src_dir: sparqlinc,
-    main_xml: 'libtracker-sparql-docs.xml',
-    scan_args: ['--ignore-headers=' + ' '.join(private_headers)],
-    content_files: [
-        'overview.xml',
-        'examples.xml',
-        'ontologies.xml',
-        'migrating-1to2.xml',
-        'sparql-and-tracker.xml',
-        'sparql-functions.xml',
-        example_files ],
-    html_assets: image_files,
-    gobject_typesfile: 'libtracker-sparql.types',
-    dependencies: tracker_sparql_dep,
-    fixxref_args: fixxref_args,
-    module_version: tracker_api_major,
-    install: true)
+gidocgen_conf = configuration_data()
+gidocgen_conf.set('version', meson.project_version())
+gidocgen_conf.set('content', ','.join(_quoted))
+gidocgen_toml = configure_file(input: 'tracker-sparql.toml.in', output: 'tracker-sparql.toml', configuration: gidocgen_conf)
 
-subdir('examples')
+custom_target(
+  'docgen',
+  input: [ gidocgen_toml, tracker_sparql_gir[0] ],
+  output: 'docs',
+  command: [
+    gidocgen,
+    'generate',
+    '--quiet',
+    #'--add-include-path=@0@'.format(meson.current_build_dir() / '../../../gtk'),
+    '--config=@INPUT0@',
+    '--output-dir=@OUTPUT@',
+    #'--no-namespace-dir',
+    '--content-dir=@0@'.format(meson.current_source_dir()),
+    '@INPUT1@',
+  ],
+  depends: tracker_sparql_gir[0],
+  depend_files: [ content ],
+  build_by_default: true)
diff --git a/docs/reference/libtracker-sparql/tracker-sparql.toml.in b/docs/reference/libtracker-sparql/tracker-sparql.toml.in
new file mode 100644
index 000000000..01b9c3ab2
--- /dev/null
+++ b/docs/reference/libtracker-sparql/tracker-sparql.toml.in
@@ -0,0 +1,35 @@
+[library]
+version = "@version@"
+browse_url = "https://gitlab.gnome.org/GNOME/tracker/"
+repository_url = "https://gitlab.gnome.org/GNOME/tracker.git"
+website_url = "https://gnome.pages.gitlab.gnome.org/tracker/"
+authors = "Tracker Development Team"
+# logo_url = 
+license = "GPL-2.1-or-later"
+description = "Tracker"
+dependencies = [ "GObject-2.0", ]
+devhelp = true
+search_index = true
+
+  [dependencies."GObject-2.0"]
+  name = "GObject"
+  description = "The base type system library"
+  docs_url = "https://developer.gnome.org/gobject/stable"
+
+[theme]
+name = "basic"
+show_index_summary = true
+show_class_hierarchy = true
+
+[source-location]
+base_url = "https://gitlab.gnome.org/GNOME/tracker/-/blob/master/"
+
+[extra]
+content_files = [
+    @content@
+]
+content_images = [
+    "images/triple-graph-1.png",
+    "images/triple-graph-2.png",
+]
+# urlmap_file = "urlmap.js"
diff --git a/docs/reference/libtracker-sparql/tutorial.md b/docs/reference/libtracker-sparql/tutorial.md
new file mode 100644
index 000000000..c0005dd3c
--- /dev/null
+++ b/docs/reference/libtracker-sparql/tutorial.md
@@ -0,0 +1,297 @@
+----
+Title: SPARQL Tutorial
+----
+
+# SPARQL Tutorial
+
+This tutorial aims to introduce you to RDF and SPARQL from the ground
+up. All examples come from the Nepomuk ontology, and even though
+the tutorial aims to be generic enough, it mentions things
+specific to Tracker, those are clearly spelled out.
+
+## RDF Triples
+
+RDF data define a graph, composed by vertices and edges. This graph is
+directed, because edges point from one vertex to another, and it is
+labeled, as those edges have a name. The unit of data in RDF is a
+triple of the form:
+
+    subject  predicate  object
+
+Or expressed visually:
+
+![Triple Graph](triple-graph-1.png)
+
+Subject and object are 2 graph vertices and the predicate is the edge,
+the accumulation of those triples form the full graph. For example,
+the following triples:
+
+```
+<a> a nfo:FileDataObject .
+<a> a nmm:MusicPiece .
+<a> nie:title "Images" .
+<a> nmm:musicAlbum <b> .
+<a> nmm:albumArtist <c> .
+<a> nmm:albumArtist <d> .
+<a> nmm:performer <e> .
+<b> a nmm:MusicAlbum .
+<b> nie:title "Go Off!" .
+<c> a nmm:Artist .
+<c> nmm:artistName "Jason Becker" .
+<d> a nmm:Artist .
+<d> nmm:artistName "Marty Friedman" .
+<e> a nmm:Artist .
+<e> nmm:artistName "Cacophony" .
+```
+
+Would visually generate the following graph:
+
+![Triple Graph](triple-graph-2.png)
+
+The dot after each triple is not (just) there for legibility, but is
+part of the syntax. The RDF triples in full length are quite
+repetitive and cumbersome to write, luckily they can be shortened by
+providing multiple objects (with `,` separator) or multiple
+predicate/object pairs (with `;` separator), the previous RDF could be
+transformed into:
+
+```
+<a> a nfo:FileDataObject, nmm:MusicPiece .
+<a> nie:title "Images" .
+<a> nmm:musicAlbum <b> .
+<a> nmm:albumArtist <c> , <d> .
+<a> nmm:performer <e> .
+<b> a nmm:MusicAlbum .
+<b> nie:title "Go Off!" .
+<c> a nmm:Artist .
+<c> nmm:artistName "Jason Becker" .
+<d> a nmm:Artist .
+<d> nmm:artistName "Marty Friedman" .
+<e> a nmm:Artist .
+<e> nmm:artistName "Cacophony" .
+```
+
+And further into:
+
+```
+<a> a nfo:FileDataObject, nmm:MusicPiece ;
+    nie:title "Images" ;
+    nmm:musicAlbum <b> ;
+    nmm:albumArtist <c>, <d> ;
+    nmm:performer <e> .
+<b> a nmm:MusicAlbum ;
+    nie:title "Go Off!" .
+<c> a nmm:Artist ;
+    nmm:artistName "Jason Becker" .
+<d> a nmm:Artist ;
+    nmm:artistName "Marty Friedman" .
+<e> a nmm:Artist ;
+    nmm:artistName "Cacophony" .
+```
+
+## SPARQL
+
+SPARQL defines a query language for RDF data. How does a query
+language for graphs work? Naturally by providing a graph to be
+matched, it is conveniently called the "graph pattern".
+
+To begin simple, the simplest query would consist of a triple with all
+3 elements defined, e.g.:
+
+```SPARQL
+ASK { <a> nie:title "Images" }
+```
+
+Which would result in `true`, as the triple does exist. The ASK query
+syntax is actually the simplest form of graph testing, resulting in a
+single boolean row/column containing whether the provided graph exists
+in the store or not. It also works for more complex graphs, for
+example:
+
+```SPARQL
+ASK { <a> nie:title "Images" ;
+          nmm:albumArtist <c> ;
+          nmm:musicAlbum <b> .
+      <b> nie:title "Go Off!" .
+      <c> nmm:artistName "Jason Becker" }
+```
+
+But of course the deal of a query language is being able to obtain the
+stored data. The `SELECT` query syntax is used for that, and variables
+are denoted with a `?` prefix, variables act as "placeholders" where
+any data will match and be available to the resultset or within the
+query as that variable name. The following query would be the opposite
+to the first `ASK` query:
+
+```SPARQL
+SELECT * { ?subject ?predicate ?object }
+```
+
+What does this query do? it provides a triple with 3 variables, that
+every known triple in the database will match. The `*` is a shortcut
+for all queried variables, the query could also be expressed as:
+
+```SPARQL
+SELECT ?subject ?predicate ?object { ?subject ?predicate ?object }
+```
+
+However, querying for all known data is most often hardly useful, this
+got unwieldly soon! Luckily, that is not necessarily the case, the
+variables may be used anywhere in the triple definition, with other
+triple elements consisting of literals you want to match for, e.g.:
+
+<!--       <example> -->
+<!-- 	<title> -->
+<!-- 	  Give me the title of resource <systemitem><a></systemitem> (Result: "Images"). -->
+<!--         </title> -->
+<!--         <programlisting language="SPARQL"> -->
+<!-- SELECT ?songName { <a> nie:title ?songName } -->
+<!-- 	</programlisting> -->
+<!--       </example> -->
+
+<!--       <example> -->
+<!-- 	<title> -->
+<!-- 	  What is this text to <b>? (Result: the nie:title) -->
+<!--         </title> -->
+<!--         <programlisting language="SPARQL"> -->
+<!-- SELECT ?predicate { <b> ?predicate "Go Off!" } -->
+<!--         </programlisting> -->
+<!--       </example> -->
+
+<!--       <example> -->
+<!-- 	<title> -->
+<!-- 	  What is the resource URI of this fine musician? (Result: <systemitem><d></systemitem>) -->
+<!--         </title> -->
+<!--         <programlisting language="SPARQL"> -->
+<!-- SELECT ?subject { ?subject nmm:artistName "Marty Friedman" } -->
+<!--         </programlisting> -->
+<!--       </example> -->
+
+<!--       <example> -->
+<!-- 	<title> -->
+<!-- 	  Give me all resources that are a music piece (Result: <systemitem><a></systemitem>) -->
+<!--         </title> -->
+<!--         <programlisting language="SPARQL"> -->
+<!-- SELECT ?song { ?song a nmm:MusicPiece } -->
+<!--         </programlisting> -->
+<!--       </example> -->
+<!--     </para> -->
+<!--     <para> -->
+<!--       And also combinations of them, for example: -->
+
+<!--       <example> -->
+<!-- 	<title> -->
+<!-- 	  Give me all predicate/object pairs for resource <systemitem><a></systemitem> -->
+<!--         </title> -->
+<!--         <programlisting language="SPARQL"> -->
+<!-- SELECT ?pred ?obj { <a> ?pred ?obj } -->
+<!--         </programlisting> -->
+<!--       </example> -->
+
+<!--       <example> -->
+<!-- 	<title> -->
+<!-- 	  <quote>The Answer to the Ultimate Question of Life, the Universe, and Everything</quote> -->
+<!--         </title> -->
+<!--         <programlisting language="SPARQL"> -->
+<!-- SELECT ?subj ?pred { ?subj ?pred 42 } -->
+<!--         </programlisting> -->
+<!--       </example> -->
+
+<!--       <example> -->
+<!-- 	<title> -->
+<!-- 	  Give me all resources that have a title, and their title. -->
+<!--         </title> -->
+<!--         <programlisting language="SPARQL"> -->
+<!-- SELECT ?subj ?obj { ?subj nie:title ?obj } -->
+<!--         </programlisting> -->
+<!--       </example> -->
+
+<!--       And of course, the graph pattern can hold more complex triple -->
+<!--       definitions, that will be matched as a whole across the stored -->
+<!--       data. for example: -->
+
+<!--       <example> -->
+<!-- 	<title> -->
+<!-- 	  Give me all songs from this fine album -->
+<!--         </title> -->
+<!--         <programlisting language="SPARQL"> -->
+<!-- SELECT ?song { ?album nie:title "Go Off!" . -->
+<!--                ?song nmm:musicAlbum ?album } -->
+<!--         </programlisting> -->
+<!--       </example> -->
+
+<!--       <example> -->
+<!-- 	<title> -->
+<!-- 	  Give me all song resources, their title, and their album title -->
+<!--         </title> -->
+<!--         <programlisting language="SPARQL"> -->
+<!-- SELECT ?song ?songTitle ?albumTitle { ?song a nmm:MusicPiece ; -->
+<!--                                             nmm:musicAlbum ?album ; -->
+<!--                                             nie:title ?songTitle . -->
+<!--                                       ?album nie:title ?albumTitle } -->
+<!--         </programlisting> -->
+<!--       </example> -->
+<!--     </para> -->
+<!--     <para> -->
+<!--       Stop a bit to think on the graph pattern expressed in the last query: -->
+<!--       <graphic fileref="triple-graph-3.png" format="PNG"></graphic> -->
+
+<!-- This pattern on one hand consists of specified data (eg. ?song must be -->
+<!-- a <systemitem>nmm:MusicPiece</systemitem>, it must have a -->
+<!-- <systemitem>nmm:musicAlbum</systemitem> and a -->
+<!-- <systemitem>nie:title</systemitem>, ?album must have a -->
+<!-- <systemitem>nie:title</systemitem>), which must all apply for a match -->
+<!-- to happen. -->
+ 
+On the other hand, the graph pattern contains a number of variables,
+some only used internally in the graph pattern, as a temporary
+variable of sorts (?album, in order to express the relation between
+?song and its album title), while other variables are requested in the
+result set.
+ 
+  <!-- FIXME: Keep writing! -->
+  <!--
+  <chapter id="tracker-tutorial-ontologies">
+    <title>Ontologies</title>
+  </chapter>
+  <chapter id="tracker-tutorial-inserting-data">
+    <title>Inserting data</title>
+  </chapter>
+  <chapter id="tracker-tutorial-updates-deletes">
+    <title>Updates and deletes</title>
+  </chapter>
+  <chapter id="tracker-tutorial-named-nodes">
+    <title>Named nodes</title>
+  </chapter>
+  <chapter id="tracker-tutorial-blank-nodes">
+    <title>Blank nodes</title>
+  </chapter>
+  <chapter id="tracker-tutorial-property-paths">
+    <title>Property paths</title>
+  </chapter>
+  <chapter id="tracker-tutorial-optional">
+    <title>Optional data</title>
+  </chapter>
+  <chapter id="tracker-tutorial-filtering">
+    <title>Filtering data</title>
+  </chapter>
+  <chapter id="tracker-tutorial-binding">
+g    <title>Binding expressions to variables</title>
+  </chapter>
+  <chapter id="tracker-tutorial-aggregates">
+    <title>Aggregates</title>
+  </chapter>
+  <chapter id="tracker-tutorial-graphs">
+    <title>Graphs</title>
+  </chapter>
+  <chapter id="tracker-tutorial-services">
+    <title>Services</title>
+  </chapter>
+  <chapter id="tracker-tutorial-import-export">
+    <title>Importing and exporting data</title>
+  </chapter>
+  <chapter id="tracker-tutorial-graph-management">
+    <title>Graph Management</title>
+  </chapter>
+  -->
+</part>
diff --git a/docs/reference/meson.build b/docs/reference/meson.build
index d44f61d20..ff133c815 100644
--- a/docs/reference/meson.build
+++ b/docs/reference/meson.build
@@ -1,24 +1,2 @@
-glib_prefix = dependency('glib-2.0').get_pkgconfig_variable('prefix')
-glib_docpath = join_paths(glib_prefix, 'share', 'gtk-doc', 'html')
-
-docpath = join_paths(datadir, 'gtk-doc')
-
-fixxref_args = [
-    '--html-dir=@0@'.format(docpath),
-    '--extra-dir=@0@'.format(join_paths(glib_docpath, 'glib')),
-    '--extra-dir=@0@'.format(join_paths(glib_docpath, 'gobject')),
-    '--extra-dir=@0@'.format(join_paths(glib_docpath, 'gio')),
-    '--extra-dir=@0@'.format(join_paths(docpath, 'libtracker-sparql')),
-]
-
-icon_images = files(
-  'images/icon-deprecated.svg',
-  'images/icon-fulltextindexed.svg',
-  'images/icon-multivalue.svg',
-  'images/icon-notify.svg',
-  'images/icon-superproperty.svg',
-)
-
 subdir('libtracker-sparql')
-
-subdir('ontology')
+# subdir('ontology')