Clean up documentation and remove junk files from install

14 files changed, 201 insertions, 114 deletions

diff --git a/doc/c/Doxyfile.in b/doc/Doxyfile.in
index 2ca5694..2ca5694 100644
--- a/doc/c/Doxyfile.in
+++ b/doc/Doxyfile.in
diff --git a/doc/c/api/meson.build b/doc/api/meson.build
index 8c8293b..8c8293b 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 e93b0e8..0000000
--- a/doc/c/index.rst
+++ /dev/null
@@ -1,14 +0,0 @@
-..
-   Copyright 2020-2022 David Robillard <d@drobilla.net>
-   SPDX-License-Identifier: ISC
-
-####
-Lilv
-####
-
-.. include:: summary.rst
-
-.. toctree::
-
-   overview
-   api/lilv
diff --git a/doc/c/meson.build b/doc/c/meson.build
deleted file mode 100644
index 53e69dc..0000000
--- a/doc/c/meson.build
+++ /dev/null
@@ -1,54 +0,0 @@
-# Copyright 2021-2022 David Robillard <d@drobilla.net>
-# SPDX-License-Identifier: 0BSD OR ISC
-
-config = configuration_data()
-config.set('LILV_VERSION', meson.project_version())
-
-conf_py = configure_file(
-  configuration: config,
-  input: files('../conf.py.in'),
-  output: 'conf.py',
-)
-
-configure_file(
-  copy: true,
-  input: files('../summary.rst'),
-  output: 'summary.rst',
-)
-
-c_rst_files = files(
-  'index.rst',
-  'overview.rst',
-  'plugins.rst',
-  'uis.rst',
-  'world.rst',
-)
-
-foreach f : c_rst_files
-  configure_file(copy: true, input: f, output: '@PLAINNAME@')
-endforeach
-
-subdir('xml')
-subdir('api')
-
-docs = custom_target(
-  'singlehtml',
-  build_by_default: true,
-  command: [sphinx_build, '-M', 'singlehtml', '@OUTDIR@', '@OUTDIR@',
-            '-E', '-q', '-t', 'singlehtml'],
-  input: [c_rst_files, c_lilv_rst, c_index_xml],
-  install: true,
-  install_dir: docdir / 'lilv-0',
-  output: 'singlehtml',
-)
-
-docs = custom_target(
-  'html',
-  build_by_default: true,
-  command: [sphinx_build, '-M', 'html', '@OUTDIR@', '@OUTDIR@',
-            '-E', '-q', '-t', 'html'],
-  input: [c_rst_files, c_lilv_rst, c_index_xml],
-  install: true,
-  install_dir: docdir / 'lilv-0',
-  output: 'html',
-)
diff --git a/doc/conf.py.in b/doc/conf.py.in
index b53e9ca..444b70a 100644
--- a/doc/conf.py.in
+++ b/doc/conf.py.in
@@ -3,10 +3,12 @@
 
 # Project information
 
-project = "Lilv"
-copyright = "2020, David Robillard"
+project = "@LILV_TITLE@"
+copyright = "2020-2023, David Robillard"
 author = "David Robillard"
 release = "@LILV_VERSION@"
+version = "@LILV_VERSION@"
+desc = "A library for loading LV2 plugins"
 
 # General configuration
 
@@ -15,6 +17,13 @@ language = "en"
 nitpicky = True
 pygments_style = "friendly"
 
+try:
+    import sphinx_lv2_theme
+
+    have_lv2_theme = True
+except ModuleNotFoundError:
+    have_lv2_theme = False
+
 # Ignore everything opaque or external for nitpicky mode
 _opaque = [
     "FILE",
@@ -41,42 +50,78 @@ nitpick_ignore = list(map(lambda x: ("c:identifier", x), _opaque))
 
 # HTML output
 
-html_theme = "sphinx_lv2_theme"
 html_copy_source = False
-html_short_title = "Lilv"
-
-if tags.has('singlehtml'):
-    html_sidebars = {
-        "**": [
-        "globaltoc.html",
-        ]
-    }
-
-    html_theme_options = {
-        "body_max_width": "65em",
-        "body_min_width": "50em",
-        "description": "A library for loading LV2 plugins",
-        "show_footer_version": True,
-        "show_logo_version": False,
-        "logo_name": True,
-        "nosidebar": False,
-        "page_width": "80em",
-        "sidebar_width": "11em",
-        "globaltoc_maxdepth": 3,
-        "globaltoc_collapse": False,
-    }
+html_secnumber_suffix = " "
+html_short_title = "@LILV_TITLE@"
+
+html_theme_options = {
+    "description": desc,
+    "logo_name": True,
+    "logo_width": "8em",
+}
 
+if tags.has("singlehtml"):
+    html_sidebars = {"**": ["globaltoc.html"]}
+    html_theme_options.update(
+        {
+            "globaltoc_collapse": False,
+            "globaltoc_maxdepth": 3,
+            "nosidebar": False,
+            "page_width": "80em",
+        }
+    )
 else:
-    html_theme_options = {
-        "body_max_width": "60em",
-        "body_min_width": "40em",
-        "description": "A library for loading LV2 plugins",
-        "show_footer_version": True,
-        "show_logo_version": False,
-        "logo_name": True,
-        "nosidebar": True,
-        "page_width": "60em",
-        "sidebar_width": "14em",
-        "globaltoc_maxdepth": 1,
-        "globaltoc_collapse": True,
-    }
+    html_theme_options.update(
+        {
+            "globaltoc_collapse": True,
+            "globaltoc_maxdepth": 1,
+            "nosidebar": True,
+            "page_width": "60em",
+        }
+    )
+
+if have_lv2_theme:
+    html_theme = "sphinx_lv2_theme"
+
+    html_theme_options.update(
+        {
+            "show_footer_version": True,
+            "show_logo_version": True,
+        }
+    )
+
+    if tags.has("singlehtml"):
+        html_theme_options.update(
+            {
+                "body_max_width": "64em",
+                "body_min_width": "64em",
+                "nosidebar": False,
+                "sidebar_width": "12em",
+            }
+        )
+
+    else:
+        html_theme_options.update(
+            {
+                "body_max_width": "60em",
+                "body_min_width": "40em",
+            }
+        )
+
+else:
+    html_theme = "alabaster"
+
+    if tags.has("singlehtml"):
+        html_theme_options = {
+            "body_max_width": "58em",
+            "body_min_width": "40em",
+            "sidebar_width": "16em",
+        }
+
+    else:
+        html_theme_options = {
+            "body_max_width": "60em",
+            "body_min_width": "40em",
+            "nosidebar": True,
+            "show_relbars": True,
+        }
diff --git a/doc/html/meson.build b/doc/html/meson.build
new file mode 100644
index 0000000..26d3a03
--- /dev/null
+++ b/doc/html/meson.build
@@ -0,0 +1,32 @@
+# 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, '-M', 'html', '@OUTDIR@' / '..', '@OUTDIR@' / '..',
+    '-t', 'html',
+  ] + sphinx_flags,
+  input: [c_rst_files, c_lilv_rst, c_index_xml, conf_py],
+  install: true,
+  install_dir: html_dir,
+  output: [
+    '_static',
+    'api',
+    'genindex.html',
+    'index.html',
+    'overview.html',
+    'plugins.html',
+    'uis.html',
+    'world.html',
+  ],
+)
+
+if not meson.is_subproject()
+  summary('Paginated HTML', get_option('prefix') / html_dir, section: 'Directories')
+endif
diff --git a/doc/summary.rst b/doc/index.rst
index 0349af1..46a9026 100644
--- a/doc/summary.rst
+++ b/doc/index.rst
@@ -2,6 +2,10 @@
    Copyright 2020-2022 David Robillard <d@drobilla.net>
    SPDX-License-Identifier: ISC
 
+####
+Lilv
+####
+
 Lilv is a library for working with LV2_ plugins.
 It provides several types and functions that can be used to discover plugins,
 investigate their data, load and run them, and save and restore their state.
@@ -10,4 +14,10 @@ Lilv is the standard implementation used by nearly all LV2 hosts.
 It implements the details of the LV2 specification on POSIX, MacOS, and Windows,
 and provides a simpler portable API for applications.
 
+.. toctree::
+
+   overview
+   api/lilv
+
 .. _LV2: http://lv2plug.in/
+
diff --git a/doc/meson.build b/doc/meson.build
index 7c633a0..787ab4f 100644
--- a/doc/meson.build
+++ b/doc/meson.build
@@ -3,22 +3,64 @@
 
 docdir = get_option('datadir') / 'doc'
 
+# 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')
+  # Configure conf.py for Sphinx
+  conf_config = configuration_data()
+  conf_config.set('LILV_SRCDIR', lilv_src_root)
+  conf_config.set('LILV_TITLE', get_option('title'))
+  conf_config.set('LILV_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',
+    'plugins.rst',
+    'uis.rst',
+    'world.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_flags = ['-E', '-a', '-q']
+  if get_option('werror')
+    sphinx_flags += ['-W']
+  endif
+
+  # Run Sphinx to generate final documentation for each format
+  foreach format : ['html', 'singlehtml']
+    if not get_option(format).disabled()
+      subdir(format)
+    endif
+  endforeach
 endif
 
 if not meson.is_subproject()
-  summary('Documentation', build_docs, bool_yn: true)
+  summary('Documentation', build_docs, bool_yn: true, section: 'Components')
 endif
-
diff --git a/doc/c/overview.rst b/doc/overview.rst
index 17ebec9..17ebec9 100644
--- a/doc/c/overview.rst
+++ b/doc/overview.rst
diff --git a/doc/c/plugins.rst b/doc/plugins.rst
index c7ad547..c7ad547 100644
--- a/doc/c/plugins.rst
+++ b/doc/plugins.rst
diff --git a/doc/singlehtml/meson.build b/doc/singlehtml/meson.build
new file mode 100644
index 0000000..4822d8c
--- /dev/null
+++ b/doc/singlehtml/meson.build
@@ -0,0 +1,26 @@
+# 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, '-M', 'singlehtml', '@OUTDIR@' / '..', '@OUTDIR@' / '..',
+    '-t', 'singlehtml',
+  ] + sphinx_flags,
+  input: [c_rst_files, c_lilv_rst, c_index_xml, conf_py],
+  install: true,
+  install_dir: singlehtml_dir,
+  output: [
+    '_static',
+    'index.html',
+  ],
+)
+
+if not meson.is_subproject()
+  summary('Unified HTML', get_option('prefix') / singlehtml_dir, section: 'Directories')
+endif
diff --git a/doc/c/uis.rst b/doc/uis.rst
index 1169060..1169060 100644
--- a/doc/c/uis.rst
+++ b/doc/uis.rst
diff --git a/doc/c/world.rst b/doc/world.rst
index 8b71165..8b71165 100644
--- a/doc/c/world.rst
+++ b/doc/world.rst
diff --git a/doc/c/xml/meson.build b/doc/xml/meson.build
index dc234f3..dc234f3 100644
--- a/doc/c/xml/meson.build
+++ b/doc/xml/meson.build