Clean up documentation configuration

3 files changed, 75 insertions, 18 deletions

diff --git a/doc/_static/custom.css b/doc/_static/custom.css
new file mode 100644
index 00000000..757c218c
--- /dev/null
+++ b/doc/_static/custom.css
@@ -0,0 +1,16 @@
+/* Copyright 2022 David Robillard <d@drobilla.net> */
+/* SPDX-License-Identifier: 0BSD or ISC */
+
+div.bodywrapper {
+  margin: 0 0 0 16em;
+}
+
+section > dl {
+  margin-bottom: 30px;
+}
+
+.struct > dd > dl.member > dt,
+.enum > dd > dl.member > dt,
+.enum-class > dd > dl.member > dt {
+  padding: 15px 0 0;
+}
diff --git a/doc/c/meson.build b/doc/c/meson.build
index a2f7eaa5..8c4934de 100644
--- a/doc/c/meson.build
+++ b/doc/c/meson.build
@@ -1,6 +1,20 @@
 # Copyright 2020-2022 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
+
 config = configuration_data()
 config.set('SERD_VERSION', meson.project_version())
 config.set('SERD_SRCDIR', serd_src_root)
@@ -12,6 +26,8 @@ conf_py = configure_file(
   output: 'conf.py',
 )
 
+# Copy hand-written documentation sources
+
 configure_file(
   copy: true,
   input: files('../summary.rst'),
@@ -27,9 +43,13 @@ 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
+
 # TODO: Add install_tag: 'doc' after requiring meson 0.60.0
 
 custom_target(
@@ -37,7 +57,7 @@ custom_target(
   build_by_default: true,
   command: [sphinx_build, '-M', 'singlehtml', '@OUTDIR@', '@OUTDIR@',
             '-E', '-q', '-t', 'singlehtml'],
-  input: [c_rst_files, c_serd_rst, c_index_xml],
+  input: [c_rst_files, c_serd_rst, c_index_xml, conf_py],
   install: true,
   install_dir: docdir / versioned_name,
   output: 'singlehtml',
@@ -48,7 +68,7 @@ custom_target(
   build_by_default: true,
   command: [sphinx_build, '-M', 'html', '@OUTDIR@', '@OUTDIR@',
             '-E', '-q', '-t', 'html'],
-  input: [c_rst_files, c_serd_rst, c_index_xml],
+  input: [c_rst_files, c_serd_rst, c_index_xml, conf_py],
   install: true,
   install_dir: docdir / versioned_name,
   output: 'html',
diff --git a/doc/conf.py.in b/doc/conf.py.in
index 7b3e8ee1..924066aa 100644
--- a/doc/conf.py.in
+++ b/doc/conf.py.in
@@ -7,6 +7,8 @@ project = "@SERD_TITLE@"
 copyright = "2022, David Robillard"
 author = "David Robillard"
 release = "@SERD_VERSION@"
+version = "@SERD_VERSION@"
+desc = "A lightweight library for working with RDF"
 
 # General configuration
 
@@ -17,6 +19,7 @@ pygments_style = "friendly"
 
 try:
     import sphinx_lv2_theme
+
     have_lv2_theme = True
 except ModuleNotFoundError:
     have_lv2_theme = False
@@ -51,14 +54,14 @@ nitpick_ignore = list(map(lambda x: ("c:identifier", x), _opaque))
 # HTML output
 
 html_copy_source = False
+html_secnumber_suffix = " "
 html_short_title = "@SERD_TITLE@"
 html_static_path = ["@SERD_SRCDIR@/doc/_static"]
-html_theme = "sphinx_lv2_theme"
 
 if have_lv2_theme:
     html_theme = "sphinx_lv2_theme"
 
-    if tags.has('singlehtml'):
+    if tags.has("singlehtml"):
         html_sidebars = {
             "**": [
                 "globaltoc.html",
@@ -68,7 +71,7 @@ if have_lv2_theme:
         html_theme_options = {
             "body_max_width": "48em",
             "body_min_width": "48em",
-            "description": "A lightweight library for working with RDF",
+            "description": desc,
             "show_footer_version": True,
             "show_logo_version": False,
             "logo": "serd.svg",
@@ -76,7 +79,7 @@ if have_lv2_theme:
             "logo_width": "8em",
             "nosidebar": False,
             "page_width": "80em",
-            "sidebar_width": "18em",
+            "sidebar_width": "12em",
             "globaltoc_maxdepth": 3,
             "globaltoc_collapse": False,
         }
@@ -85,7 +88,7 @@ if have_lv2_theme:
         html_theme_options = {
             "body_max_width": "60em",
             "body_min_width": "40em",
-            "description": "A lightweight library for working with RDF",
+            "description": desc,
             "show_footer_version": True,
             "show_logo_version": False,
             "logo": "serd.svg",
@@ -102,14 +105,32 @@ else:
 
     html_theme = "alabaster"
 
-    html_theme_options = {
-        "body_max_width": "60em",
-        "body_min_width": "40em",
-        "description": "A lightweight library for working with RDF",
-        "logo": "serd.svg",
-        "logo_name": True,
-        "page_width": "60em",
-        "sidebar_width": "14em",
-        "globaltoc_maxdepth": 1,
-        "globaltoc_collapse": True,
-    }
+    if tags.has("singlehtml"):
+        html_sidebars = {
+            "**": [
+                "globaltoc.html",
+            ]
+        }
+
+        html_theme_options = {
+            "body_max_width": "40em",
+            "body_min_width": "40em",
+            "description": desc,
+            "globaltoc_collapse": False,
+            "globaltoc_maxdepth": 3,
+            "logo": "serd.svg",
+            "nosidebar": False,
+            "page_width": "56em",
+            "sidebar_width": "16em",
+        }
+
+    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,
+        }