aboutsummaryrefslogtreecommitdiffstats
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)0
-rw-r--r--doc/c/index.rst14
-rw-r--r--doc/c/meson.build88
-rw-r--r--doc/conf.py.in102
-rw-r--r--doc/html/meson.build29
-rw-r--r--doc/index.rst (renamed from doc/summary.rst)12
-rw-r--r--doc/meson.build51
-rw-r--r--doc/overview.rst (renamed from doc/c/overview.rst)0
-rw-r--r--doc/singlehtml/meson.build26
-rw-r--r--doc/xml/meson.build (renamed from doc/c/xml/meson.build)2
11 files changed, 163 insertions, 161 deletions
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() / '..')
generated by cgit v1.2.1 (git 2.18.0) at 2024-11-06 07:27:35 +0000