summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/Doxyfile.in (renamed from doc/c/Doxyfile.in)0
-rw-r--r--doc/api/meson.build (renamed from doc/c/api/meson.build)2
-rw-r--r--doc/c/index.rst14
-rw-r--r--doc/c/meson.build53
-rw-r--r--doc/c/reference.rst15
-rw-r--r--doc/conf.py.in10
-rw-r--r--doc/html/meson.build31
-rw-r--r--doc/index.rst (renamed from doc/summary.rst)9
-rw-r--r--doc/meson.build65
-rw-r--r--doc/overview.rst (renamed from doc/c/overview.rst)0
-rw-r--r--doc/singlehtml/meson.build32
-rw-r--r--doc/xml/meson.build (renamed from doc/c/xml/meson.build)4
12 files changed, 138 insertions, 97 deletions
diff --git a/doc/c/Doxyfile.in b/doc/Doxyfile.in
index 5364912..5364912 100644
--- a/doc/c/Doxyfile.in
+++ b/doc/Doxyfile.in
diff --git a/doc/c/api/meson.build b/doc/api/meson.build
index 22aa355..ee227bc 100644
--- a/doc/c/api/meson.build
+++ b/doc/api/meson.build
@@ -1,4 +1,4 @@
-# Copyright 2021-2022 David Robillard <d@drobilla.net>
+# Copyright 2020-2023 David Robillard <d@drobilla.net>
# SPDX-License-Identifier: 0BSD OR ISC
c_sratom_rst = custom_target(
diff --git a/doc/c/index.rst b/doc/c/index.rst
deleted file mode 100644
index 4c7e619..0000000
--- a/doc/c/index.rst
+++ /dev/null
@@ -1,14 +0,0 @@
-..
- Copyright 2020-2021 David Robillard <d@drobilla.net>
- SPDX-License-Identifier: ISC
-
-######
-Sratom
-######
-
-.. include:: summary.rst
-
-.. toctree::
-
- overview
- api/sratom
diff --git a/doc/c/meson.build b/doc/c/meson.build
deleted file mode 100644
index 502dd83..0000000
--- a/doc/c/meson.build
+++ /dev/null
@@ -1,53 +0,0 @@
-# Copyright 2021-2022 David Robillard <d@drobilla.net>
-# SPDX-License-Identifier: 0BSD OR ISC
-
-config = configuration_data()
-config.set('SRATOM_VERSION', meson.project_version())
-
-conf_py = configure_file(
- configuration: config,
- input: files('../conf.py.in'),
- output: 'conf.py',
-)
-
-summary_rst = configure_file(
- copy: true,
- input: files('../summary.rst'),
- output: 'summary.rst',
-)
-
-c_rst_files = files(
- 'index.rst',
- 'overview.rst',
-)
-
-sratom_doc_rst_files = [summary_rst] + c_rst_files
-
-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_sratom_rst, c_index_xml],
- install: true,
- install_dir: docdir / 'sratom-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_sratom_rst, c_index_xml],
- install: true,
- install_dir: docdir / 'sratom-0',
- output: 'html',
-)
diff --git a/doc/c/reference.rst b/doc/c/reference.rst
deleted file mode 100644
index 5deb127..0000000
--- a/doc/c/reference.rst
+++ /dev/null
@@ -1,15 +0,0 @@
-..
- Copyright 2020-2021 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/sratom
-
diff --git a/doc/conf.py.in b/doc/conf.py.in
index 1dbf9fc..ff34db2 100644
--- a/doc/conf.py.in
+++ b/doc/conf.py.in
@@ -3,10 +3,12 @@
# Project information
-project = "Sratom"
-copyright = "2020, David Robillard"
+project = "@SRATOM_TITLE@"
+copyright = "2023, David Robillard"
author = "David Robillard"
release = "@SRATOM_VERSION@"
+version = "@SRATOM_VERSION@"
+desc = "A small library for serializing LV2 atoms"
# General configuration
@@ -52,7 +54,7 @@ if tags.has("singlehtml"):
html_theme_options = {
"body_max_width": "48em",
"body_min_width": "48em",
- "description": "A small library for serializing LV2 atoms",
+ "description": desc,
"globaltoc_collapse": False,
"globaltoc_maxdepth": 3,
"logo_name": True,
@@ -67,7 +69,7 @@ else:
html_theme_options = {
"body_max_width": "60em",
"body_min_width": "40em",
- "description": "A small library for serializing LV2 atoms",
+ "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..a6d5ef9
--- /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_sratom_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 84714ba..43eeac3 100644
--- a/doc/summary.rst
+++ b/doc/index.rst
@@ -2,8 +2,17 @@
Copyright 2020-2021 David Robillard <d@drobilla.net>
SPDX-License-Identifier: ISC
+######
+Sratom
+######
+
Sratom is a small library for serializing `LV2 atoms`_. Sratom reads/writes
atoms from/to RDF, allowing them to be converted between binary and text or
stored in a model.
+.. toctree::
+
+ overview
+ api/sratom
+
.. _LV2 atoms: http://lv2plug.in/ns/ext/atom
diff --git a/doc/meson.build b/doc/meson.build
index 4bccb1f..a9d95ab 100644
--- a/doc/meson.build
+++ b/doc/meson.build
@@ -3,21 +3,72 @@
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('SRATOM_SRCDIR', sratom_src_root)
+ conf_config.set('SRATOM_TITLE', get_option('title'))
+ conf_config.set('SRATOM_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()
- 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 4884839..4884839 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..35244a7
--- /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_sratom_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 cf1b148..119445e 100644
--- a/doc/c/xml/meson.build
+++ b/doc/xml/meson.build
@@ -1,8 +1,6 @@
-# Copyright 2021-2022 David Robillard <d@drobilla.net>
+# Copyright 2020-2023 David Robillard <d@drobilla.net>
# SPDX-License-Identifier: 0BSD OR ISC
-doxygen = find_program('doxygen')
-
config = configuration_data()
config.set('SRATOM_SRCDIR', sratom_src_root)
config.set('DOX_OUTPUT', meson.current_build_dir() / '..')
generated by cgit v1.2.1 (git 2.18.0) at 2024-11-22 00:27:45 +0000