diff options
| -rw-r--r-- | doc/conf.py.in | 109 | ||||
| -rw-r--r-- | doc/html/meson.build | 30 | ||||
| -rw-r--r-- | doc/index.rst | 4 | ||||
| -rw-r--r-- | doc/meson.build | 98 | ||||
| -rw-r--r-- | doc/singlehtml/meson.build | 24 | ||||
| -rw-r--r-- | doc/summary.rst | 5 | ||||
| -rw-r--r-- | meson.build | 31 | ||||
| -rw-r--r-- | meson_options.txt | 6 |
8 files changed, 176 insertions, 131 deletions
diff --git a/doc/conf.py.in b/doc/conf.py.in index 1fa288f..6b3c415 100644 --- a/doc/conf.py.in +++ b/doc/conf.py.in @@ -1,10 +1,10 @@ -# Copyright 2021-2022 David Robillard <d@drobilla.net> +# Copyright 2021-2023 David Robillard <d@drobilla.net> # SPDX-License-Identifier: 0BSD OR ISC # Project information project = "Zix" -copyright = "2011-2022, David Robillard" +copyright = "2011-2023, David Robillard" author = "David Robillard" release = "@ZIX_VERSION@" version = "@ZIX_VERSION@" @@ -64,72 +64,75 @@ html_copy_source = False html_secnumber_suffix = " " html_short_title = "@ZIX_TITLE@" -if have_lv2_theme: - html_theme = "sphinx_lv2_theme" - - if tags.has("singlehtml"): - html_sidebars = { - "**": [ - "globaltoc.html", - ] - } +html_theme_options = { + "description": desc, + "logo_name": True, +} - html_theme_options = { - "body_max_width": "46em", - "body_min_width": "46em", - "description": desc, +if tags.has("singlehtml"): + html_sidebars = {"**": ["globaltoc.html"]} + html_theme_options.update( + { "globaltoc_collapse": False, "globaltoc_maxdepth": 3, - "logo_name": True, "nosidebar": False, "page_width": "80em", - "show_footer_version": True, - "show_logo_version": True, - "sidebar_width": "14em", } - - else: - html_theme_options = { - "body_max_width": "60em", - "body_min_width": "46em", - "description": desc, - "logo_name": True, + ) +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" + + html_theme_options.update( + { "show_footer_version": True, "show_logo_version": True, - "sidebar_width": "14em", } + ) + + if tags.has("singlehtml"): + html_theme_options.update( + { + "body_max_width": "62em", + "body_min_width": "62em", + "sidebar_width": "14em", + } + ) + + else: + html_theme_options.update( + { + "body_max_width": "60em", + "body_min_width": "40em", + } + ) else: html_theme = "alabaster" html_static_path = ["@ZIX_SRCDIR@/doc/_static"] if tags.has("singlehtml"): - html_sidebars = { - "**": [ - "globaltoc.html", - ] - } - - html_theme_options = { - "body_max_width": "48em", - "body_min_width": "48em", - "description": desc, - "globaltoc_collapse": False, - "globaltoc_maxdepth": 3, - "logo_name": True, - "nosidebar": False, - "page_width": "80em", - "sidebar_width": "16em", - } + html_theme_options.update( + { + "body_max_width": "58em", + "body_min_width": "40em", + "sidebar_width": "14em", + } + ) else: - html_theme_options = { - "body_max_width": "60em", - "body_min_width": "40em", - "description": desc, - "logo_name": True, - "nosidebar": True, - "page_width": "60em", - "show_relbars": True, - } + html_theme_options.update( + { + "body_max_width": "60em", + "body_min_width": "40em", + "show_relbars": True, + } + ) diff --git a/doc/html/meson.build b/doc/html/meson.build new file mode 100644 index 0000000..7403e95 --- /dev/null +++ b/doc/html/meson.build @@ -0,0 +1,30 @@ +# Copyright 2021-2023 David Robillard <d@drobilla.net> +# SPDX-License-Identifier: 0BSD OR ISC + +html_dir = docdir / versioned_name / 'html' + +custom_target( + 'html', + build_by_default: true, + command: [ + sphinx_build, '-M', 'html', '@OUTDIR@' / '..', '@OUTDIR@' / '..', + '-t', 'html', + ] + sphinx_flags, + input: [c_rst_files, c_zix_rst, c_index_xml, conf_py], + install: true, + install_dir: html_dir, + output: [ + '_static', + 'allocation.html', + 'api', + 'error_handling.html', + 'genindex.html', + 'index.html', + 'string_views.html', + 'using_zix.html', + ], +) + +if not meson.is_subproject() + summary('Paginated HTML', get_option('prefix') / html_dir, section: 'Directories') +endif diff --git a/doc/index.rst b/doc/index.rst index 56062e6..c4f19bf 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,12 +1,12 @@ .. - Copyright 2020-2022 David Robillard <d@drobilla.net> + Copyright 2020-2023 David Robillard <d@drobilla.net> SPDX-License-Identifier: ISC ### Zix ### -.. include:: summary.rst +Zix is a lightweight C library of portability wrappers and data structures. .. toctree:: :numbered: diff --git a/doc/meson.build b/doc/meson.build index 78ed876..b3dd5b0 100644 --- a/doc/meson.build +++ b/doc/meson.build @@ -3,9 +3,11 @@ docdir = get_option('datadir') / 'doc' +# 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 if doxygen.found() and sphinx_build.found() sphinxygen = find_program('sphinxygen', required: false) if not sphinxygen.found() @@ -16,18 +18,18 @@ else sphinxygen = disabler() endif +# Build documentation if all required tools are found +build_docs = doxygen.found() and sphinx_build.found() and sphinxygen.found() +if not meson.is_subproject() + summary('Documentation', build_docs, bool_yn: true, section: 'Configuration') +endif + build_docs = doxygen.found() and sphinxygen.found() and sphinx_build.found() if build_docs - - # Check for Sphinx LV2 theme - + # Warn if the "official" theme isn't present pymod = import('python') - sphinx_lv2_theme_python = pymod.find_installation( - modules: ['sphinx_lv2_theme'], - required: false - ) - - if not sphinx_lv2_theme_python.found() + 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 @@ -48,71 +50,43 @@ if build_docs # Generated API Reference + # Configure conf.py for Sphinx + config = configuration_data() + config.set('ZIX_SRCDIR', zix_src_root) + config.set('ZIX_TITLE', get_option('title')) + config.set('ZIX_VERSION', meson.project_version()) + conf_py = configure_file( + configuration: config, + input: files('conf.py.in'), + output: 'conf.py', + ) + + # Copy hand-written documentation files c_rst_files = files( 'allocation.rst', 'error_handling.rst', 'index.rst', 'string_views.rst', - 'summary.rst', 'using_zix.rst', ) - - c_doc_files = c_rst_files + files( - 'overview_code.c', - ) - - foreach f : c_doc_files + foreach f : c_rst_files + files('overview_code.c') configure_file(copy: true, input: f, output: '@PLAINNAME@') endforeach - config = configuration_data() - config.set('ZIX_VERSION', meson.project_version()) - config.set('ZIX_SRCDIR', zix_src_root) - config.set('ZIX_TITLE', get_option('title')) - - conf_py = configure_file( - configuration: config, - input: files('conf.py.in'), - output: 'conf.py', - ) - + # Generate reference documentation input with Doxygen and Sphinxygen subdir('xml') subdir('api') - sphinx_options = [ - '-D', 'release=@0@'.format(meson.project_version()), - '-E', - '-W', - '-a', - '-q', - ] - - doc_inputs = c_rst_files + [conf_py, c_zix_rst, c_index_xml] - - custom_target( - 'singlehtml', - build_by_default: true, - command: [ - sphinx_build, '-M', 'singlehtml', '@OUTDIR@', '@OUTDIR@', - '-W', '-E', '-q', '-t', 'singlehtml', - ] + sphinx_options, - input: doc_inputs, - install: true, - install_dir: docdir / versioned_name, - output: 'singlehtml', - ) - - custom_target( - 'html', - build_by_default: true, - command: [ - sphinx_build, '-M', 'html', '@OUTDIR@', '@OUTDIR@', - '-W', '-E', '-q', '-t', 'html', - ] + sphinx_options, - input: doc_inputs, - install: true, - install_dir: docdir / versioned_name, - output: 'html', - ) + # 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/singlehtml/meson.build b/doc/singlehtml/meson.build new file mode 100644 index 0000000..178e2dd --- /dev/null +++ b/doc/singlehtml/meson.build @@ -0,0 +1,24 @@ +# Copyright 2021-2023 David Robillard <d@drobilla.net> +# SPDX-License-Identifier: 0BSD OR ISC + +singlehtml_dir = docdir / versioned_name / 'singlehtml' + +custom_target( + 'singlehtml', + build_by_default: true, + command: [ + sphinx_build, '-M', 'singlehtml', '@OUTDIR@' / '..', '@OUTDIR@' / '..', + '-t', 'singlehtml', + ] + sphinx_flags, + input: [c_rst_files, c_zix_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/summary.rst b/doc/summary.rst deleted file mode 100644 index aa169df..0000000 --- a/doc/summary.rst +++ /dev/null @@ -1,5 +0,0 @@ -.. - Copyright 2020-2022 David Robillard <d@drobilla.net> - SPDX-License-Identifier: ISC - -Zix is a lightweight C library of portability wrappers and data structures. diff --git a/meson.build b/meson.build index 1ca5ec4..720bbca 100644 --- a/meson.build +++ b/meson.build @@ -444,6 +444,28 @@ if not get_option('benchmarks').disabled() subdir('benchmark') endif +# Display top-level summary (augmented in subdirectories) +if not meson.is_subproject() + summary( + { + 'Tests': not get_option('tests').disabled(), + 'Benchmarks': build_benchmarks, + }, + bool_yn: true, + section: 'Configuration', + ) + + summary( + { + 'Install prefix': get_option('prefix'), + 'Headers': get_option('prefix') / get_option('includedir'), + 'Libraries': get_option('prefix') / get_option('libdir'), + }, + bool_yn: true, + section: 'Directories', + ) +endif + ############################# # Scripts and Documentation # ############################# @@ -453,12 +475,3 @@ subdir('scripts') if not get_option('docs').disabled() subdir('doc') endif - -if not meson.is_subproject() - summary('Benchmarks', build_benchmarks, bool_yn: true) - summary('Tests', not get_option('tests').disabled(), bool_yn: true) - - summary('Install prefix', get_option('prefix')) - summary('Headers', get_option('prefix') / get_option('includedir')) - summary('Libraries', get_option('prefix') / get_option('libdir')) -endif diff --git a/meson_options.txt b/meson_options.txt index 1545314..3eac738 100644 --- a/meson_options.txt +++ b/meson_options.txt @@ -10,12 +10,18 @@ option('checks', type: 'feature', value: 'enabled', yield: true, option('docs', type: 'feature', value: 'auto', yield: true, description: 'Build documentation') +option('html', type: 'feature', value: 'auto', yield: true, + description: 'Build paginated HTML documentation') + option('lint', type: 'boolean', value: false, yield: true, description: 'Run code quality checks') option('posix', type: 'feature', value: 'auto', yield: true, description: 'Use POSIX system facilities') +option('singlehtml', type: 'feature', value: 'auto', yield: true, + description: 'Build single-page HTML documentation') + option('threads', type: 'feature', value: 'auto', yield: true, description: 'Enable thread support') |