aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorDavid Robillard <d@drobilla.net>2022-12-04 13:18:16 -0500
committerDavid Robillard <d@drobilla.net>2022-12-04 13:32:46 -0500
commit77353fba14db23f3919bebc392dab7ff3ea02010 (patch)
tree870271cf1c556b5565250943ba81b753618baee6
parent79ba155516166b8b7be14ab30c22f6f6d93b550f (diff)
downloadserd-77353fba14db23f3919bebc392dab7ff3ea02010.tar.gz
serd-77353fba14db23f3919bebc392dab7ff3ea02010.tar.bz2
serd-77353fba14db23f3919bebc392dab7ff3ea02010.zip
Clean up documentation configuration
-rw-r--r--doc/_static/custom.css16
-rw-r--r--doc/c/meson.build24
-rw-r--r--doc/conf.py.in53
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,
+ }