From ce8a14731e78aa68b79f34396ad5dc3d7d7b8ea3 Mon Sep 17 00:00:00 2001 From: David Robillard Date: Sat, 2 Sep 2023 19:23:21 -0400 Subject: Clean up documentation and remove junk files from install --- doc/Doxyfile.in | 31 ++++++++++++++++++++++ doc/api/meson.build | 9 +++++++ doc/c/Doxyfile.in | 31 ---------------------- doc/c/api/meson.build | 9 ------- doc/c/index.rst | 14 ---------- doc/c/overview.rst | 16 ------------ doc/c/reference.rst | 15 ----------- doc/c/xml/meson.build | 21 --------------- doc/conf.py.in | 12 +++++---- doc/html/meson.build | 31 ++++++++++++++++++++++ doc/index.rst | 23 ++++++++++++++++ doc/meson.build | 65 +++++++++++++++++++++++++++++++++++++++++----- doc/overview.rst | 16 ++++++++++++ doc/singlehtml/meson.build | 32 +++++++++++++++++++++++ doc/summary.rst | 14 ---------- doc/xml/meson.build | 21 +++++++++++++++ 16 files changed, 228 insertions(+), 132 deletions(-) create mode 100644 doc/Doxyfile.in create mode 100644 doc/api/meson.build delete mode 100644 doc/c/Doxyfile.in delete mode 100644 doc/c/api/meson.build delete mode 100644 doc/c/index.rst delete mode 100644 doc/c/overview.rst delete mode 100644 doc/c/reference.rst delete mode 100644 doc/c/xml/meson.build create mode 100644 doc/html/meson.build create mode 100644 doc/index.rst create mode 100644 doc/overview.rst create mode 100644 doc/singlehtml/meson.build delete mode 100644 doc/summary.rst create mode 100644 doc/xml/meson.build (limited to 'doc') diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in new file mode 100644 index 0000000..0d787bc --- /dev/null +++ b/doc/Doxyfile.in @@ -0,0 +1,31 @@ +# Copyright 2021-2022 David Robillard +# SPDX-License-Identifier: 0BSD OR ISC + +PROJECT_NAME = Suil +PROJECT_BRIEF = "A library for loading LV2 plugin UIs" + +QUIET = YES +WARN_AS_ERROR = NO +WARN_IF_UNDOCUMENTED = NO +WARN_NO_PARAMDOC = NO + +JAVADOC_AUTOBRIEF = YES + +CASE_SENSE_NAMES = YES +HIDE_IN_BODY_DOCS = YES +REFERENCES_LINK_SOURCE = NO + +GENERATE_HTML = NO +GENERATE_LATEX = NO +GENERATE_XML = YES +XML_PROGRAMLISTING = NO +SHOW_FILES = NO + +MACRO_EXPANSION = YES +PREDEFINED = SUIL_API + +RECURSIVE = YES +STRIP_FROM_PATH = @SUIL_SRCDIR@ +INPUT = @SUIL_SRCDIR@/include + +OUTPUT_DIRECTORY = @DOX_OUTPUT@ diff --git a/doc/api/meson.build b/doc/api/meson.build new file mode 100644 index 0000000..6c629e6 --- /dev/null +++ b/doc/api/meson.build @@ -0,0 +1,9 @@ +# Copyright 2021-2022 David Robillard +# SPDX-License-Identifier: 0BSD OR ISC + +c_suil_rst = custom_target( + 'suil.rst', + command: [sphinxygen, '-f', '@INPUT0@', '@OUTDIR@'], + input: [c_index_xml] + c_rst_files, + output: 'suil.rst', +) diff --git a/doc/c/Doxyfile.in b/doc/c/Doxyfile.in deleted file mode 100644 index 0d787bc..0000000 --- a/doc/c/Doxyfile.in +++ /dev/null @@ -1,31 +0,0 @@ -# Copyright 2021-2022 David Robillard -# SPDX-License-Identifier: 0BSD OR ISC - -PROJECT_NAME = Suil -PROJECT_BRIEF = "A library for loading LV2 plugin UIs" - -QUIET = YES -WARN_AS_ERROR = NO -WARN_IF_UNDOCUMENTED = NO -WARN_NO_PARAMDOC = NO - -JAVADOC_AUTOBRIEF = YES - -CASE_SENSE_NAMES = YES -HIDE_IN_BODY_DOCS = YES -REFERENCES_LINK_SOURCE = NO - -GENERATE_HTML = NO -GENERATE_LATEX = NO -GENERATE_XML = YES -XML_PROGRAMLISTING = NO -SHOW_FILES = NO - -MACRO_EXPANSION = YES -PREDEFINED = SUIL_API - -RECURSIVE = YES -STRIP_FROM_PATH = @SUIL_SRCDIR@ -INPUT = @SUIL_SRCDIR@/include - -OUTPUT_DIRECTORY = @DOX_OUTPUT@ diff --git a/doc/c/api/meson.build b/doc/c/api/meson.build deleted file mode 100644 index 6c629e6..0000000 --- a/doc/c/api/meson.build +++ /dev/null @@ -1,9 +0,0 @@ -# Copyright 2021-2022 David Robillard -# SPDX-License-Identifier: 0BSD OR ISC - -c_suil_rst = custom_target( - 'suil.rst', - command: [sphinxygen, '-f', '@INPUT0@', '@OUTDIR@'], - input: [c_index_xml] + c_rst_files, - output: 'suil.rst', -) diff --git a/doc/c/index.rst b/doc/c/index.rst deleted file mode 100644 index 7f8eb92..0000000 --- a/doc/c/index.rst +++ /dev/null @@ -1,14 +0,0 @@ -.. - Copyright 2020-2022 David Robillard - SPDX-License-Identifier: ISC - -#### -Suil -#### - -.. include:: summary.rst - -.. toctree:: - - overview - api/suil diff --git a/doc/c/overview.rst b/doc/c/overview.rst deleted file mode 100644 index 71937b2..0000000 --- a/doc/c/overview.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. - Copyright 2020-2022 David Robillard - SPDX-License-Identifier: ISC - -######## -Overview -######## - -.. default-domain:: c -.. highlight:: c - -The complete API is declared in ``suil.h``: - -.. code-block:: c - - #include diff --git a/doc/c/reference.rst b/doc/c/reference.rst deleted file mode 100644 index 1512f42..0000000 --- a/doc/c/reference.rst +++ /dev/null @@ -1,15 +0,0 @@ -.. - Copyright 2020-2022 David Robillard - SPDX-License-Identifier: ISC - -############# -API Reference -############# - -This section contains the generated documentation for all symbols in the public -API. - -.. toctree:: - - api/suil - diff --git a/doc/c/xml/meson.build b/doc/c/xml/meson.build deleted file mode 100644 index bbbf130..0000000 --- a/doc/c/xml/meson.build +++ /dev/null @@ -1,21 +0,0 @@ -# Copyright 2021-2022 David Robillard -# 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() / '..') - -c_doxyfile = configure_file( - configuration: config, - input: files('../Doxyfile.in'), - output: 'Doxyfile', -) - -c_index_xml = custom_target( - 'index.xml', - command: [doxygen, '@INPUT0@'], - input: [c_doxyfile] + c_headers, - output: 'index.xml', -) diff --git a/doc/conf.py.in b/doc/conf.py.in index 3193610..7b6a2db 100644 --- a/doc/conf.py.in +++ b/doc/conf.py.in @@ -1,12 +1,14 @@ -# Copyright 2020-2021 David Robillard +# Copyright 2020-2023 David Robillard # SPDX-License-Identifier: ISC # Project information -project = "Suil" -copyright = "2020, David Robillard" +project = "@SUIL_TITLE@" +copyright = "2023, David Robillard" author = "David Robillard" release = "@SUIL_VERSION@" +version = "@SUIL_VERSION@" +desc = "A library for loading LV2 plugin UIs" # General configuration @@ -42,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, @@ -57,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..e55f026 --- /dev/null +++ b/doc/html/meson.build @@ -0,0 +1,31 @@ +# Copyright 2021-2023 David Robillard +# 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_suil_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/index.rst b/doc/index.rst new file mode 100644 index 0000000..7f81dbd --- /dev/null +++ b/doc/index.rst @@ -0,0 +1,23 @@ +.. + Copyright 2020-2023 David Robillard + SPDX-License-Identifier: ISC + +#### +Suil +#### + +Suil is a library for loading and wrapping LV2 plugin UIs. + +With Suil, +a host written in one supported toolkit can embed a plugin UI written in another. +Suil insulates hosts from toolkit libraries used by plugin UIs. +For example, +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 index 3f6f0bf..b6f6402 100644 --- a/doc/meson.build +++ b/doc/meson.build @@ -1,21 +1,72 @@ -# Copyright 2021-2022 David Robillard +# Copyright 2021-2023 David Robillard # SPDX-License-Identifier: 0BSD OR ISC 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('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 + 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() diff --git a/doc/overview.rst b/doc/overview.rst new file mode 100644 index 0000000..71937b2 --- /dev/null +++ b/doc/overview.rst @@ -0,0 +1,16 @@ +.. + Copyright 2020-2022 David Robillard + SPDX-License-Identifier: ISC + +######## +Overview +######## + +.. default-domain:: c +.. highlight:: c + +The complete API is declared in ``suil.h``: + +.. code-block:: c + + #include diff --git a/doc/singlehtml/meson.build b/doc/singlehtml/meson.build new file mode 100644 index 0000000..7303085 --- /dev/null +++ b/doc/singlehtml/meson.build @@ -0,0 +1,32 @@ +# Copyright 2021-2023 David Robillard +# 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_suil_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/summary.rst b/doc/summary.rst deleted file mode 100644 index 57c101e..0000000 --- a/doc/summary.rst +++ /dev/null @@ -1,14 +0,0 @@ -.. - Copyright 2020-2022 David Robillard - SPDX-License-Identifier: ISC - -Suil is a library for loading and wrapping LV2 plugin UIs. - -With Suil, -a host written in one supported toolkit can embed a plugin UI written in another. -Suil insulates hosts from toolkit libraries used by plugin UIs. -For example, -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. diff --git a/doc/xml/meson.build b/doc/xml/meson.build new file mode 100644 index 0000000..bbbf130 --- /dev/null +++ b/doc/xml/meson.build @@ -0,0 +1,21 @@ +# Copyright 2021-2022 David Robillard +# 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() / '..') + +c_doxyfile = configure_file( + configuration: config, + input: files('../Doxyfile.in'), + output: 'Doxyfile', +) + +c_index_xml = custom_target( + 'index.xml', + command: [doxygen, '@INPUT0@'], + input: [c_doxyfile] + c_headers, + output: 'index.xml', +) -- cgit v1.2.1