Clean up documentation and remove junk files from install

14 files changed, 170 insertions, 167 deletions

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index d0625f81..d4f5cfa4 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -147,11 +147,11 @@ pages:
   stage: deploy
   script:
     - mkdir public
-    - mkdir public/c
+    - mkdir public/doc
     - mkdir public/man
     - mv build/meson-logs/coveragereport/ public/coverage
-    - mv build/doc/c/html/ public/c/html/
-    - mv build/doc/c/singlehtml/ public/c/singlehtml/
+    - mv build/doc/html/ public/doc/html/
+    - mv build/doc/singlehtml/ public/doc/singlehtml/
     - mv build/doc/serdi.html public/man/serdi.html
     - mv build/doc/mandoc.css public/man/mandoc.css
   needs:
diff --git a/NEWS b/NEWS
index 49b437c8..b32fb3a7 100644
--- a/NEWS
+++ b/NEWS
@@ -25,12 +25,13 @@ serd (0.31.5) unstable; urgency=medium
   * Make URI writing stricter by default
   * Make serd_reader_read_chunk() work with NQuads
   * Override pkg-config dependency within meson
+  * Remove junk files from documentation install
   * Remove support for writing Turtle named inline nodes extension
   * Replace duplicated dox_to_sphinx script with sphinxygen dependency
   * Test header for warnings more strictly
   * Update standard test suites
 
- -- David Robillard <d@drobilla.net>  Fri, 05 May 2023 17:28:53 +0000
+ -- David Robillard <d@drobilla.net>  Fri, 12 May 2023 02:42:30 +0000
 
 serd (0.30.16) stable; urgency=medium
 
diff --git a/README.md b/README.md
index fa15c878..3e26e300 100644
--- a/README.md
+++ b/README.md
@@ -55,8 +55,8 @@ Documentation
 -------------
 
  * [Installation instructions](INSTALL.md)
- * [Single-page API reference](https://drobilla.gitlab.io/serd/c/singlehtml)
- * [Paginated API reference](https://drobilla.gitlab.io/serd/c/html)
+ * [Single-page API reference](https://drobilla.gitlab.io/serd/doc/singlehtml/)
+ * [Paginated API reference](https://drobilla.gitlab.io/serd/doc/html/)
  * [`serdi` man page](https://drobilla.gitlab.io/serd/man/serdi.html)
 
 Versioning
diff --git a/doc/c/Doxyfile.in b/doc/Doxyfile.in
index a33ec7c4..a33ec7c4 100644
--- a/doc/c/Doxyfile.in
+++ b/doc/Doxyfile.in
diff --git a/doc/c/api/meson.build b/doc/api/meson.build
index b40af2f1..b40af2f1 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 451b5d85..00000000
--- a/doc/c/index.rst
+++ /dev/null
@@ -1,14 +0,0 @@
-..
-   Copyright 2020-2021 David Robillard <d@drobilla.net>
-   SPDX-License-Identifier: ISC
-
-####
-Serd
-####
-
-.. include:: summary.rst
-
-.. toctree::
-
-   overview
-   api/serd
diff --git a/doc/c/meson.build b/doc/c/meson.build
deleted file mode 100644
index f81a692a..00000000
--- a/doc/c/meson.build
+++ /dev/null
@@ -1,88 +0,0 @@
-# Copyright 2020-2023 David Robillard <d@drobilla.net>
-# SPDX-License-Identifier: 0BSD OR ISC
-
-# Check for Sphinx LV2 theme
-
-pymod = import('python')
-sphinx_lv2_theme_python = pymod.find_installation(
-  modules: ['sphinx_lv2_theme'],
-  required: false
-)
-
-if not sphinx_lv2_theme_python.found()
-  warning('Missing sphinx_lv2_theme module, falling back to alabaster')
-endif
-
-# Generate Sphinx configuration file
-
-conf_config = configuration_data()
-conf_config.set('SERD_SRCDIR', serd_src_root)
-conf_config.set('SERD_TITLE', get_option('title'))
-conf_config.set('SERD_VERSION', meson.project_version())
-
-conf_py = configure_file(
-  configuration: conf_config,
-  input: files('../conf.py.in'),
-  output: 'conf.py',
-)
-
-# Copy hand-written documentation sources
-
-configure_file(
-  copy: true,
-  input: files('../summary.rst'),
-  output: 'summary.rst',
-)
-
-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 sources
-
-subdir('xml')
-subdir('api')
-
-# Generate documentation with sphinx
-
-sphinx_flags = ['-E', '-a', '-q']
-if get_option('werror')
-  sphinx_flags += ['-W']
-endif
-
-# TODO: Add install_tag: 'doc' after requiring meson 0.60.0
-
-if not get_option('singlehtml').disabled()
-  custom_target(
-    'singlehtml',
-    build_by_default: true,
-    command: [
-      sphinx_build,
-      '-M', 'singlehtml', '@OUTDIR@', '@OUTDIR@', '-t', 'singlehtml',
-    ] + sphinx_flags,
-    input: [c_rst_files, c_serd_rst, c_index_xml, conf_py],
-    install: true,
-    install_dir: docdir / versioned_name,
-    output: 'singlehtml',
-  )
-endif
-
-if not get_option('html').disabled()
-  custom_target(
-    'html',
-    build_by_default: true,
-    command: [
-      sphinx_build,
-      '-M', 'html', '@OUTDIR@', '@OUTDIR@', '-t', 'html',
-    ] + sphinx_flags,
-    input: [c_rst_files, c_serd_rst, c_index_xml, conf_py],
-    install: true,
-    install_dir: docdir / versioned_name,
-    output: 'html',
-  )
-endif
diff --git a/doc/conf.py.in b/doc/conf.py.in
index 51b37217..5037d217 100644
--- a/doc/conf.py.in
+++ b/doc/conf.py.in
@@ -4,7 +4,7 @@
 # Project information
 
 project = "@SERD_TITLE@"
-copyright = "2022, David Robillard"
+copyright = "2022-2023, David Robillard"
 author = "David Robillard"
 release = "@SERD_VERSION@"
 version = "@SERD_VERSION@"
@@ -46,69 +46,68 @@ html_secnumber_suffix = " "
 html_short_title = "@SERD_TITLE@"
 html_static_path = ["@SERD_SRCDIR@/doc/_static"]
 
+html_theme_options = {
+    "description": desc,
+    "logo": "serd.svg",
+    "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.update(
+        {
+            "globaltoc_collapse": True,
+            "globaltoc_maxdepth": 1,
+            "nosidebar": True,
+            "page_width": "60em",
+        }
+    )
+
 if have_lv2_theme:
     html_theme = "sphinx_lv2_theme"
 
-    if tags.has("singlehtml"):
-        html_sidebars = {
-            "**": [
-                "globaltoc.html",
-            ]
-        }
-
-        html_theme_options = {
-            "body_max_width": "48em",
-            "body_min_width": "48em",
-            "description": desc,
+    html_theme_options.update(
+        {
             "show_footer_version": True,
-            "show_logo_version": False,
-            "logo": "serd.svg",
-            "logo_name": True,
-            "logo_width": "8em",
-            "nosidebar": False,
-            "page_width": "80em",
-            "sidebar_width": "12em",
-            "globaltoc_maxdepth": 3,
-            "globaltoc_collapse": False,
+            "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 = {
-            "body_max_width": "60em",
-            "body_min_width": "40em",
-            "description": desc,
-            "show_footer_version": True,
-            "show_logo_version": False,
-            "logo": "serd.svg",
-            "logo_name": True,
-            "logo_width": "8em",
-            "nosidebar": True,
-            "page_width": "60em",
-            "sidebar_width": "14em",
-            "globaltoc_maxdepth": 1,
-            "globaltoc_collapse": True,
-        }
+        html_theme_options.update(
+            {
+                "body_max_width": "60em",
+                "body_min_width": "40em",
+            }
+        )
 
 else:
-
     html_theme = "alabaster"
 
     if tags.has("singlehtml"):
-        html_sidebars = {
-            "**": [
-                "globaltoc.html",
-            ]
-        }
-
         html_theme_options = {
-            "body_max_width": "40em",
+            "body_max_width": "58em",
             "body_min_width": "40em",
-            "description": desc,
-            "globaltoc_collapse": False,
-            "globaltoc_maxdepth": 3,
-            "logo": "serd.svg",
-            "nosidebar": False,
-            "page_width": "56em",
             "sidebar_width": "16em",
         }
 
@@ -116,9 +115,6 @@ else:
         html_theme_options = {
             "body_max_width": "60em",
             "body_min_width": "40em",
-            "description": desc,
-            "logo": "serd.svg",
             "nosidebar": True,
-            "page_width": "60em",
             "show_relbars": True,
         }
diff --git a/doc/html/meson.build b/doc/html/meson.build
new file mode 100644
index 00000000..a6f1d6fe
--- /dev/null
+++ b/doc/html/meson.build
@@ -0,0 +1,29 @@
+# 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_serd_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('Paginated HTML', get_option('prefix') / html_dir, section: 'Directories')
+endif
diff --git a/doc/summary.rst b/doc/index.rst
index 16a236eb..73e1a5fb 100644
--- a/doc/summary.rst
+++ b/doc/index.rst
@@ -1,9 +1,19 @@
 ..
-   Copyright 2020-2021 David Robillard <d@drobilla.net>
+   Copyright 2020-2023 David Robillard <d@drobilla.net>
    SPDX-License-Identifier: ISC
 
+####
+Serd
+####
+
 Serd is a lightweight C library for reading and writing RDF in Turtle_, NTriples_, NQuads_, and TriG_.
 
+.. toctree::
+   :numbered:
+
+   overview
+   api/serd
+
 .. _Turtle: http://www.w3.org/TR/turtle/
 .. _NTriples: http://www.w3.org/TR/n-triples/
 .. _NQuads: http://www.w3.org/TR/n-quads/
diff --git a/doc/meson.build b/doc/meson.build
index 9366e8a0..7bc4c0f4 100644
--- a/doc/meson.build
+++ b/doc/meson.build
@@ -7,22 +7,67 @@ docdir = get_option('datadir') / 'doc'
 # Reference #
 #############
 
+# Find required programs
 doxygen = find_program('doxygen', required: get_option('docs'))
 sphinx_build = find_program('sphinx-build', 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
-else
-  sphinxygen = disabler()
 endif
 
+# Build documentation if all required tools are found
 build_docs = doxygen.found() and sphinxygen.found() and sphinx_build.found()
+if not meson.is_subproject()
+  summary('Documentation', build_docs, bool_yn: true, section: 'Configuration')
+endif
+
 if build_docs
-  subdir('c')
+  # Warn if the "official" theme isn't present
+  pymod = import('python')
+  doc_modules = ['sphinx_lv2_theme']
+  if not pymod.find_installation(modules: doc_modules, required: false).found()
+    warning('Missing sphinx_lv2_theme module, falling back to alabaster')
+  endif
+
+  # Configure conf.py for Sphinx
+  conf_config = configuration_data()
+  conf_config.set('SERD_SRCDIR', serd_src_root)
+  conf_config.set('SERD_TITLE', get_option('title'))
+  conf_config.set('SERD_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_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
 
 #############
diff --git a/doc/c/overview.rst b/doc/overview.rst
index b03615b9..b03615b9 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 00000000..a15a69ec
--- /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_serd_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/xml/meson.build b/doc/xml/meson.build
index 34852719..503eff3a 100644
--- a/doc/c/xml/meson.build
+++ b/doc/xml/meson.build
@@ -1,8 +1,6 @@
 # Copyright 2020-2022 David Robillard <d@drobilla.net>
 # SPDX-License-Identifier: 0BSD OR ISC
 
-doxygen = find_program('doxygen')
-
 config = configuration_data()
 config.set('SERD_SRCDIR', serd_src_root)
 config.set('DOX_OUTPUT', meson.current_build_dir() / '..')