Clean up documentation and remove junk files from install

11 files changed, 138 insertions, 42 deletions

diff --git a/doc/c/Doxyfile.in b/doc/Doxyfile.in
index 0d787bc..0d787bc 100644
--- a/doc/c/Doxyfile.in
+++ b/doc/Doxyfile.in
diff --git a/doc/c/api/meson.build b/doc/api/meson.build
index 6c629e6..6c629e6 100644
--- a/doc/c/api/meson.build
+++ b/doc/api/meson.build
diff --git a/doc/c/index.rst b/doc/c/index.rst
deleted file mode 100644
index 7f8eb92..0000000
--- a/doc/c/index.rst
+++ /dev/null
@@ -1,14 +0,0 @@
-..
-   Copyright 2020-2022 David Robillard <d@drobilla.net>
-   SPDX-License-Identifier: ISC
-
-####
-Suil
-####
-
-.. include:: summary.rst
-
-.. toctree::
-
-   overview
-   api/suil
diff --git a/doc/c/reference.rst b/doc/c/reference.rst
deleted file mode 100644
index 1512f42..0000000
--- a/doc/c/reference.rst
+++ /dev/null
@@ -1,15 +0,0 @@
-..
-   Copyright 2020-2022 David Robillard <d@drobilla.net>
-   SPDX-License-Identifier: ISC
-
-#############
-API Reference
-#############
-
-This section contains the generated documentation for all symbols in the public
-API.
-
-.. toctree::
-
-   api/suil
-
diff --git a/doc/conf.py.in b/doc/conf.py.in
index 3193610..7b6a2db 100644
--- a/doc/conf.py.in
+++ b/doc/conf.py.in
@@ -1,12 +1,14 @@
-# Copyright 2020-2021 David Robillard <d@drobilla.net>
+# Copyright 2020-2023 David Robillard <d@drobilla.net>
 # SPDX-License-Identifier: ISC
 
 # Project information
 
-project = "Suil"
-copyright = "2020, David Robillard"
+project = "@SUIL_TITLE@"
+copyright = "2023, David Robillard"
 author = "David Robillard"
 release = "@SUIL_VERSION@"
+version = "@SUIL_VERSION@"
+desc = "A library for loading LV2 plugin UIs"
 
 # General configuration
 
@@ -42,7 +44,7 @@ if tags.has("singlehtml"):
     html_theme_options = {
         "body_max_width": "48em",
         "body_min_width": "48em",
-        "description": "A library for loading LV2 plugin UIs",
+        "description": desc,
         "globaltoc_collapse": False,
         "globaltoc_maxdepth": 3,
         "logo_name": True,
@@ -57,7 +59,7 @@ else:
     html_theme_options = {
         "body_max_width": "60em",
         "body_min_width": "40em",
-        "description": "A library for loading LV2 plugin UIs",
+        "description": desc,
         "globaltoc_collapse": True,
         "globaltoc_maxdepth": 1,
         "logo_name": True,
diff --git a/doc/html/meson.build b/doc/html/meson.build
new file mode 100644
index 0000000..e55f026
--- /dev/null
+++ b/doc/html/meson.build
@@ -0,0 +1,31 @@
+# Copyright 2021-2023 David Robillard <d@drobilla.net>
+# SPDX-License-Identifier: 0BSD OR ISC
+
+html_dir = docdir / versioned_name / 'html'
+
+# TODO: Add install_tag: 'doc' after requiring meson 0.60.0
+
+custom_target(
+  'html',
+  build_by_default: true,
+  command: sphinx_build_command + [
+    '-b', 'html',
+    '-t', 'html',
+    sphinx_in_dir,
+    '@OUTDIR@',
+  ],
+  input: [c_rst_files, c_suil_rst, c_index_xml, conf_py],
+  install: true,
+  install_dir: html_dir,
+  output: [
+    '_static',
+    'api',
+    'genindex.html',
+    'index.html',
+    'overview.html',
+  ],
+)
+
+if not meson.is_subproject()
+  summary('HTML', get_option('prefix') / html_dir, section: 'Directories')
+endif
diff --git a/doc/summary.rst b/doc/index.rst
index 57c101e..7f81dbd 100644
--- a/doc/summary.rst
+++ b/doc/index.rst
@@ -1,7 +1,11 @@
 ..
-   Copyright 2020-2022 David Robillard <d@drobilla.net>
+   Copyright 2020-2023 David Robillard <d@drobilla.net>
    SPDX-License-Identifier: ISC
 
+####
+Suil
+####
+
 Suil is a library for loading and wrapping LV2 plugin UIs.
 
 With Suil,
@@ -12,3 +16,8 @@ a Gtk host can embed a Qt UI without linking against Qt at compile time.
 
 Suil also handles the embedding of native platform UIs (which are recommended) in common toolkits,
 for example embedding an X11 UI in a Gtk host.
+
+.. toctree::
+
+   overview
+   api/suil
diff --git a/doc/meson.build b/doc/meson.build
index 3f6f0bf..b6f6402 100644
--- a/doc/meson.build
+++ b/doc/meson.build
@@ -1,21 +1,72 @@
-# Copyright 2021-2022 David Robillard <d@drobilla.net>
+# Copyright 2021-2023 David Robillard <d@drobilla.net>
 # SPDX-License-Identifier: 0BSD OR ISC
 
 docdir = get_option('datadir') / 'doc'
 
+#############
+# Reference #
+#############
+
+# Find required programs
 doxygen = find_program('doxygen', required: get_option('docs'))
-sphinxygen = find_program('sphinxygen', required: false)
 sphinx_build = find_program('sphinx-build', required: get_option('docs'))
 
-if not sphinxygen.found()
-  subproject('sphinxygen')
-  sphinxygen = find_program('sphinxygen', required: get_option('docs'))
+# Find sphinxygen or fall back to subproject
+sphinxygen = disabler()
+if doxygen.found() and sphinx_build.found()
+  sphinxygen = find_program('sphinxygen', required: false)
+  if not sphinxygen.found()
+    subproject('sphinxygen')
+    sphinxygen = find_program('sphinxygen', required: get_option('docs'))
+  endif
 endif
 
+# Build documentation if all required tools are found
 build_docs = doxygen.found() and sphinxygen.found() and sphinx_build.found()
-
 if build_docs
-  subdir('c')
+  # Warn if the "official" theme isn't present
+  pymod = import('python')
+  doc_modules = ['sphinx_lv2_theme']
+  py = pymod.find_installation('python3', modules: doc_modules, required: false)
+  if not py.found()
+    warning('Missing sphinx_lv2_theme module, falling back to alabaster')
+  endif
+
+  # Configure conf.py for Sphinx
+  conf_config = configuration_data()
+  conf_config.set('SUIL_SRCDIR', suil_src_root)
+  conf_config.set('SUIL_TITLE', get_option('title'))
+  conf_config.set('SUIL_VERSION', meson.project_version())
+  conf_py = configure_file(
+    configuration: conf_config,
+    input: files('conf.py.in'),
+    output: 'conf.py',
+  )
+
+  # Copy hand-written documentation files
+  c_rst_files = files('index.rst', 'overview.rst')
+  foreach f : c_rst_files
+    configure_file(copy: true, input: f, output: '@PLAINNAME@')
+  endforeach
+
+  # Generate reference documentation input with Doxygen and Sphinxygen
+  subdir('xml')
+  subdir('api')
+
+  # Build strict Sphinx flags, with termination on warnings if werror=true
+  sphinx_in_dir = meson.current_build_dir()
+  sphinx_flags = ['-d', sphinx_in_dir / '.doctrees', '-E', '-a', '-q']
+  if get_option('werror')
+    sphinx_flags += ['-W']
+  endif
+
+  # Run Sphinx to generate final documentation for each format
+  sphinx_build_command = [sphinx_build] + sphinx_flags
+  foreach format : ['html', 'singlehtml']
+    if not get_option(format).disabled()
+      subdir(format)
+    endif
+  endforeach
 endif
 
 if not meson.is_subproject()
diff --git a/doc/c/overview.rst b/doc/overview.rst
index 71937b2..71937b2 100644
--- a/doc/c/overview.rst
+++ b/doc/overview.rst
diff --git a/doc/singlehtml/meson.build b/doc/singlehtml/meson.build
new file mode 100644
index 0000000..7303085
--- /dev/null
+++ b/doc/singlehtml/meson.build
@@ -0,0 +1,32 @@
+# Copyright 2021-2023 David Robillard <d@drobilla.net>
+# SPDX-License-Identifier: 0BSD OR ISC
+
+singlehtml_dir = docdir / versioned_name / 'singlehtml'
+
+# TODO: Add install_tag: 'doc' after requiring meson 0.60.0
+
+custom_target(
+  'singlehtml',
+  build_by_default: true,
+  command: sphinx_build_command + [
+    '-b', 'singlehtml',
+    '-t', 'singlehtml',
+    sphinx_in_dir,
+    '@OUTDIR@',
+  ],
+  input: [c_rst_files, c_suil_rst, c_index_xml, conf_py],
+  install: true,
+  install_dir: singlehtml_dir,
+  output: [
+    '_static',
+    'index.html',
+  ],
+)
+
+if not meson.is_subproject()
+  summary(
+    'Single HTML',
+    get_option('prefix') / singlehtml_dir,
+    section: 'Directories',
+  )
+endif
diff --git a/doc/c/xml/meson.build b/doc/xml/meson.build
index bbbf130..bbbf130 100644
--- a/doc/c/xml/meson.build
+++ b/doc/xml/meson.build