From 7c8682a1b53713b3263034bc8db3cdb5839968b5 Mon Sep 17 00:00:00 2001 From: David Robillard Date: Sat, 2 Sep 2023 19:00:54 -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/meson.build | 53 ------------------------------------- doc/c/overview.rst | 16 ------------ doc/c/reference.rst | 15 ----------- doc/c/xml/meson.build | 21 --------------- doc/conf.py.in | 10 ++++--- doc/html/meson.build | 31 ++++++++++++++++++++++ doc/index.rst | 18 +++++++++++++ doc/meson.build | 65 +++++++++++++++++++++++++++++++++++++++++----- doc/overview.rst | 16 ++++++++++++ doc/singlehtml/meson.build | 32 +++++++++++++++++++++++ doc/summary.rst | 9 ------- doc/xml/meson.build | 19 ++++++++++++++ 17 files changed, 220 insertions(+), 179 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/meson.build 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..5364912 --- /dev/null +++ b/doc/Doxyfile.in @@ -0,0 +1,31 @@ +# Copyright 2021-2022 David Robillard +# SPDX-License-Identifier: 0BSD OR ISC + +PROJECT_NAME = Sratom +PROJECT_BRIEF = "A small library for serializing LV2 atoms" + +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 = SRATOM_API + +RECURSIVE = YES +STRIP_FROM_PATH = @SRATOM_SRCDIR@ +INPUT = @SRATOM_SRCDIR@/include + +OUTPUT_DIRECTORY = @DOX_OUTPUT@ diff --git a/doc/api/meson.build b/doc/api/meson.build new file mode 100644 index 0000000..ee227bc --- /dev/null +++ b/doc/api/meson.build @@ -0,0 +1,9 @@ +# Copyright 2020-2023 David Robillard +# SPDX-License-Identifier: 0BSD OR ISC + +c_sratom_rst = custom_target( + 'sratom.rst', + command: [sphinxygen, '-f', '@INPUT0@', '@OUTDIR@'], + input: [c_index_xml] + c_rst_files, + output: 'sratom.rst', +) diff --git a/doc/c/Doxyfile.in b/doc/c/Doxyfile.in deleted file mode 100644 index 5364912..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 = Sratom -PROJECT_BRIEF = "A small library for serializing LV2 atoms" - -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 = SRATOM_API - -RECURSIVE = YES -STRIP_FROM_PATH = @SRATOM_SRCDIR@ -INPUT = @SRATOM_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 22aa355..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_sratom_rst = custom_target( - 'sratom.rst', - command: [sphinxygen, '-f', '@INPUT0@', '@OUTDIR@'], - input: [c_index_xml] + c_rst_files, - output: 'sratom.rst', -) 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 - 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 -# 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/overview.rst b/doc/c/overview.rst deleted file mode 100644 index 4884839..0000000 --- a/doc/c/overview.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. - Copyright 2020-2021 David Robillard - SPDX-License-Identifier: ISC - -######## -Overview -######## - -.. default-domain:: c -.. highlight:: c - -The complete API is declared in ``sratom.h``: - -.. code-block:: c - - #include 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 - 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/c/xml/meson.build b/doc/c/xml/meson.build deleted file mode 100644 index cf1b148..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('SRATOM_SRCDIR', sratom_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 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 +# 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/index.rst b/doc/index.rst new file mode 100644 index 0000000..43eeac3 --- /dev/null +++ b/doc/index.rst @@ -0,0 +1,18 @@ +.. + Copyright 2020-2021 David Robillard + 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/overview.rst b/doc/overview.rst new file mode 100644 index 0000000..4884839 --- /dev/null +++ b/doc/overview.rst @@ -0,0 +1,16 @@ +.. + Copyright 2020-2021 David Robillard + SPDX-License-Identifier: ISC + +######## +Overview +######## + +.. default-domain:: c +.. highlight:: c + +The complete API is declared in ``sratom.h``: + +.. code-block:: c + + #include 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 +# 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/summary.rst b/doc/summary.rst deleted file mode 100644 index 84714ba..0000000 --- a/doc/summary.rst +++ /dev/null @@ -1,9 +0,0 @@ -.. - Copyright 2020-2021 David Robillard - SPDX-License-Identifier: ISC - -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. - -.. _LV2 atoms: http://lv2plug.in/ns/ext/atom diff --git a/doc/xml/meson.build b/doc/xml/meson.build new file mode 100644 index 0000000..119445e --- /dev/null +++ b/doc/xml/meson.build @@ -0,0 +1,19 @@ +# Copyright 2020-2023 David Robillard +# SPDX-License-Identifier: 0BSD OR ISC + +config = configuration_data() +config.set('SRATOM_SRCDIR', sratom_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