summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/Doxyfile.in (renamed from doc/c/Doxyfile)11
-rw-r--r--doc/api/meson.build9
-rw-r--r--doc/c/index.rst5
-rw-r--r--doc/c/reference.rst11
-rw-r--r--doc/c/wscript39
-rw-r--r--doc/conf.py.in13
-rw-r--r--doc/html/meson.build32
-rw-r--r--doc/index.rst (renamed from doc/suil.rst)9
-rw-r--r--doc/meson.build77
-rw-r--r--doc/overview.rst (renamed from doc/c/overview.rst)4
-rw-r--r--doc/singlehtml/meson.build33
-rw-r--r--doc/xml/meson.build30
12 files changed, 211 insertions, 62 deletions
diff --git a/doc/c/Doxyfile b/doc/Doxyfile.in
index ee7a427..0d787bc 100644
--- a/doc/c/Doxyfile
+++ b/doc/Doxyfile.in
@@ -1,3 +1,6 @@
+# Copyright 2021-2022 David Robillard <d@drobilla.net>
+# SPDX-License-Identifier: 0BSD OR ISC
+
PROJECT_NAME = Suil
PROJECT_BRIEF = "A library for loading LV2 plugin UIs"
@@ -19,8 +22,10 @@ XML_PROGRAMLISTING = NO
SHOW_FILES = NO
MACRO_EXPANSION = YES
-PREDEFINED = SUIL_API \
+PREDEFINED = SUIL_API
-INPUT = ../../include/suil/suil.h
+RECURSIVE = YES
+STRIP_FROM_PATH = @SUIL_SRCDIR@
+INPUT = @SUIL_SRCDIR@/include
-OUTPUT_DIRECTORY = .
+OUTPUT_DIRECTORY = @DOX_OUTPUT@
diff --git a/doc/api/meson.build b/doc/api/meson.build
new file mode 100644
index 0000000..a5cecf8
--- /dev/null
+++ b/doc/api/meson.build
@@ -0,0 +1,9 @@
+# Copyright 2021-2022 David Robillard <d@drobilla.net>
+# SPDX-License-Identifier: 0BSD OR ISC
+
+api_suil_rst = custom_target(
+ 'suil.rst',
+ command: [sphinxygen, '-f', '@INPUT0@', '@OUTDIR@'],
+ input: doxygen_xml,
+ output: 'suil.rst',
+)
diff --git a/doc/c/index.rst b/doc/c/index.rst
deleted file mode 100644
index b616761..0000000
--- a/doc/c/index.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-.. toctree::
-
- suil
- overview
- reference
diff --git a/doc/c/reference.rst b/doc/c/reference.rst
deleted file mode 100644
index 893bc4f..0000000
--- a/doc/c/reference.rst
+++ /dev/null
@@ -1,11 +0,0 @@
-#############
-API Reference
-#############
-
-This section contains the generated documentation for all symbols in the public
-API.
-
-.. toctree::
-
- api/suil
-
diff --git a/doc/c/wscript b/doc/c/wscript
deleted file mode 100644
index ae074bc..0000000
--- a/doc/c/wscript
+++ /dev/null
@@ -1,39 +0,0 @@
-#!/usr/bin/env python
-
-def build(bld):
- dox_to_sphinx = bld.path.find_node("../../scripts/dox_to_sphinx.py")
- index_xml = bld.path.get_bld().make_node("xml/index.xml")
-
- files = [
- ("../suil.rst", "sphinx/suil.rst"),
- ("index.rst", "sphinx/index.rst"),
- ("overview.rst", "sphinx/overview.rst"),
- ("reference.rst", "sphinx/reference.rst"),
- ]
-
- # Run Doxygen to generate XML documentation
- bld(features="doxygen", doxyfile="Doxyfile")
-
- # Substitute variables to make Sphinx configuration file
- bld(features="subst",
- source="../conf.py.in",
- target="sphinx/conf.py",
- SERD_VERSION=bld.env.SERD_VERSION)
-
- # Copy static documentation files to Sphinx build directory
- for f in files:
- bld(features="subst", is_copy=True, source=f[0], target=f[1])
-
- # Generate Sphinx markup from Doxygen XML
- bld.add_group()
- bld(rule="${PYTHON} " + dox_to_sphinx.abspath() + " -f ${SRC} ${TGT}",
- source=index_xml,
- target="sphinx/api/")
-
- # Run Sphinx to generate HTML documentation
- doc_dir = bld.env.DOCDIR + "/suil-%s/" % bld.env.SUIL_MAJOR_VERSION
- bld(features="sphinx",
- sphinx_source=bld.path.get_bld().make_node("sphinx"),
- sphinx_output_format="singlehtml",
- sphinx_options=["-E", "-q", "-t", "singlehtml"],
- install_path=doc_dir + "c/singlehtml/")
diff --git a/doc/conf.py.in b/doc/conf.py.in
index 423bbea..2b80ec2 100644
--- a/doc/conf.py.in
+++ b/doc/conf.py.in
@@ -1,9 +1,14 @@
+# Copyright 2020-2025 David Robillard <d@drobilla.net>
+# SPDX-License-Identifier: ISC
+
# Project information
-project = "Suil"
-copyright = "2020, David Robillard"
+project = "@SUIL_TITLE@"
+copyright = "2025, David Robillard"
author = "David Robillard"
release = "@SUIL_VERSION@"
+version = "@SUIL_VERSION@"
+desc = "A library for loading LV2 plugin UIs"
# General configuration
@@ -39,7 +44,7 @@ if tags.has("singlehtml"):
html_theme_options = {
"body_max_width": "48em",
"body_min_width": "48em",
- "description": "A library for loading LV2 plugin UIs",
+ "description": desc,
"globaltoc_collapse": False,
"globaltoc_maxdepth": 3,
"logo_name": True,
@@ -54,7 +59,7 @@ else:
html_theme_options = {
"body_max_width": "60em",
"body_min_width": "40em",
- "description": "A library for loading LV2 plugin UIs",
+ "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..7a41dc5
--- /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_command + [
+ '-b', 'html',
+ '-t', 'html',
+ sphinx_in_dir,
+ '@OUTDIR@',
+ ],
+ input: [api_suil_rst, conf_py, sphinx_input],
+ install: true,
+ install_dir: html_dir,
+ output: [
+ 'index.html',
+
+ '_static',
+ 'api',
+ 'genindex.html',
+ 'overview.html',
+ ],
+)
+
+if not meson.is_subproject()
+ summary('HTML', get_option('prefix') / html_dir, section: 'Directories')
+endif
diff --git a/doc/suil.rst b/doc/index.rst
index c5dc5ab..7f81dbd 100644
--- a/doc/suil.rst
+++ b/doc/index.rst
@@ -1,3 +1,7 @@
+..
+ Copyright 2020-2023 David Robillard <d@drobilla.net>
+ SPDX-License-Identifier: ISC
+
####
Suil
####
@@ -12,3 +16,8 @@ a Gtk host can embed a Qt UI without linking against Qt at compile time.
Suil also handles the embedding of native platform UIs (which are recommended) in common toolkits,
for example embedding an X11 UI in a Gtk host.
+
+.. toctree::
+
+ overview
+ api/suil
diff --git a/doc/meson.build b/doc/meson.build
new file mode 100644
index 0000000..4db8c74
--- /dev/null
+++ b/doc/meson.build
@@ -0,0 +1,77 @@
+# Copyright 2021-2023 David Robillard <d@drobilla.net>
+# SPDX-License-Identifier: 0BSD OR ISC
+
+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
+endif
+
+# Build documentation if all required tools are found
+build_docs = doxygen.found() and sphinxygen.found() and sphinx_build.found()
+if build_docs
+ # 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('SUIL_SRCDIR', suil_src_root)
+ conf_config.set('SUIL_TITLE', get_option('title'))
+ conf_config.set('SUIL_VERSION', meson.project_version())
+ conf_py = configure_file(
+ configuration: conf_config,
+ input: files('conf.py.in'),
+ output: 'conf.py',
+ )
+
+ # Copy hand-written documentation files
+ rst_sources = files('index.rst', 'overview.rst')
+ sphinx_input = []
+ foreach f : rst_sources
+ sphinx_input += [
+ 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 = ['-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, section: 'Components')
+endif
diff --git a/doc/c/overview.rst b/doc/overview.rst
index e8d61b1..71937b2 100644
--- a/doc/c/overview.rst
+++ b/doc/overview.rst
@@ -1,3 +1,7 @@
+..
+ Copyright 2020-2022 David Robillard <d@drobilla.net>
+ SPDX-License-Identifier: ISC
+
########
Overview
########
diff --git a/doc/singlehtml/meson.build b/doc/singlehtml/meson.build
new file mode 100644
index 0000000..0398b32
--- /dev/null
+++ b/doc/singlehtml/meson.build
@@ -0,0 +1,33 @@
+# 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: [api_suil_rst, conf_py, sphinx_input],
+ install: true,
+ install_dir: singlehtml_dir,
+ output: [
+ 'index.html',
+
+ '_static',
+ ],
+)
+
+if not meson.is_subproject()
+ summary(
+ 'Single HTML',
+ get_option('prefix') / singlehtml_dir,
+ section: 'Directories',
+ )
+endif
diff --git a/doc/xml/meson.build b/doc/xml/meson.build
new file mode 100644
index 0000000..e49aeaf
--- /dev/null
+++ b/doc/xml/meson.build
@@ -0,0 +1,30 @@
+# Copyright 2021-2022 David Robillard <d@drobilla.net>
+# SPDX-License-Identifier: 0BSD OR ISC
+
+doxygen = find_program('doxygen')
+
+config = configuration_data()
+config.set('SUIL_SRCDIR', suil_src_root)
+config.set('DOX_OUTPUT', meson.current_build_dir() / '..')
+
+doxyfile = configure_file(
+ configuration: config,
+ input: files('../Doxyfile.in'),
+ output: 'Doxyfile',
+)
+
+doxygen_xml = custom_target(
+ 'index.xml',
+ command: [doxygen, '@INPUT0@'],
+ input: [doxyfile] + c_headers,
+ output: [
+ 'index.xml',
+
+ 'group__suil.xml',
+ 'group__suil__callbacks.xml',
+ 'group__suil__host.xml',
+ 'group__suil__instance.xml',
+ 'group__suil__library.xml',
+ 'suil_8h.xml',
+ ],
+)
generated by cgit v1.2.1 (git 2.18.0) at 2025-05-12 01:59:36 +0000