docs: Migrate documentation to gi-docgen

Move away from hotdoc, and port the documentation infrastructure
to use gi-docgen. We still do fixup devhelp2 files in order to
include ontology items as search terms, and we still do prefer
to ship the pre-generated documentation in the tarball, in order
to avoid a host of dependencies like graphviz for the people
building from tarballs.

It is not the first time that porting to gi-docgen was attempted,
this is partially based on work by Daniele Nicolodi <daniele@grinta.net>.

1 files changed, 67 insertions, 42 deletions

diff --git a/docs/reference/libtracker-sparql/meson.build b/docs/reference/libtracker-sparql/meson.build
index b6dad9c9a..d55a15b06 100644
--- a/docs/reference/libtracker-sparql/meson.build
+++ b/docs/reference/libtracker-sparql/meson.build
@@ -1,13 +1,21 @@
 fs = import('fs')
 
-if fs.exists('devhelp')
+if fs.exists('doc')
   # Special case for tarballs, install the pre-generated docs
-  install_subdir('devhelp/books',
-    install_dir: join_paths(datadir, 'devhelp'))
+  install_subdir('doc',
+    install_dir: datadir)
   subdir_done()
 endif
 
-hotdoc = import('hotdoc')
+gidocgen_dep = dependency('gi-docgen', fallback: ['gi-docgen', 'dummy_dep'])
+gidocgen = find_program('gi-docgen')
+
+ontology_introductions = [
+  'nie-introduction.md',
+  'nmm-introduction.md',
+  'nco-introduction.md',
+  'mfo-introduction.md',
+]
 
 base_ontology_docs = custom_target('ontology-docgen',
     output: ['dc-ontology.md'],
@@ -18,7 +26,7 @@ base_ontology_docs = custom_target('ontology-docgen',
               '--introduction-dir', meson.current_source_dir(),
               '--ontology-description-dir', join_paths(source_root, 'src/ontologies/')],
     depends: tracker_docgen,
-    depend_files: [base_ontology],
+    depend_files: [base_ontology, ontology_introductions],
     build_by_default: true,
 )
 
@@ -30,55 +38,72 @@ nepomuk_ontology_docs = custom_target('nepomuk-docgen',
               '--output-dir', meson.current_build_dir(),
               '--introduction-dir', meson.current_source_dir()],
     depends: tracker_docgen,
-    depend_files: [base_ontology],
+    depend_files: [nepomuk, ontology_introductions],
     build_by_default: true,
 )
 
+generated_content = [
+  'xsd-ontology.md',
+  'rdf-ontology.md',
+  'nrl-ontology.md',
+  'dc-ontology.md',
+
+  'nie-ontology.md',
+  'nao-ontology.md',
+  'nco-ontology.md',
+  'nfo-ontology.md',
+  'nmm-ontology.md',
+  'mfo-ontology.md',
+  'tracker-ontology.md',
+  'slo-ontology.md',
+  'osinfo-ontology.md',
+]
+
 content = [
   'overview.md',
   'examples.md',
+  'tutorial.md',
   'ontologies.md',
+  'sparql-functions.md',
+  'sparql-and-tracker.md',
   'limits.md',
   'performance.md',
-  'sparql-and-tracker.md',
-  'sparql-functions.md',
-  'migrating-2to3.md',
-  'tutorial.md',
   'security.md',
+  'migrating-2to3.md',
 ]
 
-required_hotdoc_extensions = [
-  'gi-extension',
-  'devhelp-extension',
-  'syntax-highlighting-extension',
-]
-
-foreach ext: required_hotdoc_extensions
-  if not hotdoc.has_extensions(ext)
-    error('Documentation enabled but HotDoc extension "@0@" is missing'.format(ext))
-  endif
+# The TOML gi-docgen configuration wants a list of quoted file names.
+content_quoted = []
+foreach c : content + generated_content
+  content_quoted += '"@0@"'.format(c)
 endforeach
 
-docs_name = 'Tracker'
-hotdoc.generate_doc(docs_name,
-  project_version: tracker_version,
-  languages: [ 'c', 'python', 'javascript' ],
-  gi_c_sources: [libtracker_sparql_sources, libtracker_sparql_public_headers],
-  gi_sources: [tracker_sparql_gir[0].full_path()],
-  sitemap: 'sitemap.txt',
-  index: 'index.md',
-  gi_index: 'gi-index.md',
-  gi_smart_index: true,
-  gi_c_source_roots: [sparqlinc],
-  dependencies: [tracker_sparql_dep, base_ontology_docs, nepomuk_ontology_docs],
-  extra_assets: [join_paths(meson.current_source_dir(), 'images')],
-  html_theme: 'https://github.com/hotdoc/hotdoc_lumen_theme/releases/download/0.13.2/hotdoc_lumen_theme-0.13.2.tar.xz?sha256=5721189b7e985f27381ee20137f4a9003049a70a75ab1221a69fd04d27e752bc',
-  html_extra_theme: join_paths(meson.current_source_dir(), 'theme-extra'),
-  syntax_highlighting_activate: true,
-  devhelp_activate: true,
-  devhelp_online: 'https://gnome.pages.gitlab.gnome.org/tracker/docs/developer/',
-  install: true,
-)
+gidocgen_conf = configuration_data()
+gidocgen_conf.set('version', meson.project_version())
+gidocgen_conf.set('content', ','.join(content_quoted))
+
+gidocgen_toml = configure_file(
+  input: 'tracker-sparql.toml.in',
+  output: 'tracker-sparql.toml',
+  configuration: gidocgen_conf)
+
+reference = custom_target(
+  'docgen',
+  input: [ gidocgen_toml, tracker_sparql_gir[0] ],
+  output: 'doc',
+  command: [
+    gidocgen,
+    'generate',
+    '--quiet',
+    '--config=@INPUT0@',
+    '--output-dir=@OUTPUT@',
+    '--content-dir=@0@'.format(meson.current_source_dir()),
+    '--content-dir=@0@'.format(meson.current_build_dir()),
+    '@INPUT1@',
+  ],
+  depends: [tracker_sparql_gir[0], base_ontology_docs, nepomuk_ontology_docs],
+  depend_files: content)
 
-meson.add_install_script('install-devhelp.sh', docs_name)
-meson.add_dist_script('dist-docs.sh', docs_name)
+docs_name = 'Tracker-3.0'
+meson.add_install_script('install-devhelp.sh', docs_name, reference)
+meson.add_dist_script('dist-docs.sh', docs_name, reference.full_path())