From 60cbe5b9b6d42bd850c5ea39c06b6e182f9c2645 Mon Sep 17 00:00:00 2001 From: David Robillard Date: Thu, 11 May 2023 22:43:02 -0400 Subject: Clean up documentation and remove junk files from install --- doc/Doxyfile.in | 39 +++++++++++++++++ doc/api/meson.build | 9 ++++ doc/c/Doxyfile.in | 39 ----------------- doc/c/api/meson.build | 9 ---- doc/c/index.rst | 14 ------- doc/c/meson.build | 88 -------------------------------------- doc/c/overview.rst | 26 ------------ doc/c/xml/meson.build | 21 ---------- doc/conf.py.in | 102 ++++++++++++++++++++++----------------------- doc/html/meson.build | 29 +++++++++++++ doc/index.rst | 20 +++++++++ doc/meson.build | 51 +++++++++++++++++++++-- doc/overview.rst | 26 ++++++++++++ doc/singlehtml/meson.build | 26 ++++++++++++ doc/summary.rst | 10 ----- doc/xml/meson.build | 19 +++++++++ 16 files changed, 265 insertions(+), 263 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/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 00000000..a33ec7c4 --- /dev/null +++ b/doc/Doxyfile.in @@ -0,0 +1,39 @@ +# Copyright 2021-2022 David Robillard +# SPDX-License-Identifier: 0BSD OR ISC + +PROJECT_NAME = Serd +PROJECT_BRIEF = "A lightweight C library for working with RDF data" + +QUIET = YES +WARN_AS_ERROR = YES +WARN_IF_UNDOCUMENTED = NO +WARN_NO_PARAMDOC = NO + +JAVADOC_AUTOBRIEF = YES + +FULL_PATH_NAMES = NO +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 = SERD_ALLOCATED \ + SERD_API \ + SERD_CONST_FUNC= \ + SERD_DEPRECATED_BY(x)= \ + SERD_DISABLE_DEPRECATED \ + SERD_NONNULL= \ + SERD_NULLABLE= \ + SERD_PURE_FUNC= + +RECURSIVE = YES +STRIP_FROM_PATH = @SERD_SRCDIR@ +INPUT = @SERD_SRCDIR@/include + +OUTPUT_DIRECTORY = @DOX_OUTPUT@ diff --git a/doc/api/meson.build b/doc/api/meson.build new file mode 100644 index 00000000..b40af2f1 --- /dev/null +++ b/doc/api/meson.build @@ -0,0 +1,9 @@ +# Copyright 2020-2022 David Robillard +# SPDX-License-Identifier: 0BSD OR ISC + +c_serd_rst = custom_target( + 'serd.rst', + command: [sphinxygen, '-f', '@INPUT0@', '@OUTDIR@'], + input: [c_index_xml] + c_rst_files, + output: 'serd.rst', +) diff --git a/doc/c/Doxyfile.in b/doc/c/Doxyfile.in deleted file mode 100644 index a33ec7c4..00000000 --- a/doc/c/Doxyfile.in +++ /dev/null @@ -1,39 +0,0 @@ -# Copyright 2021-2022 David Robillard -# SPDX-License-Identifier: 0BSD OR ISC - -PROJECT_NAME = Serd -PROJECT_BRIEF = "A lightweight C library for working with RDF data" - -QUIET = YES -WARN_AS_ERROR = YES -WARN_IF_UNDOCUMENTED = NO -WARN_NO_PARAMDOC = NO - -JAVADOC_AUTOBRIEF = YES - -FULL_PATH_NAMES = NO -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 = SERD_ALLOCATED \ - SERD_API \ - SERD_CONST_FUNC= \ - SERD_DEPRECATED_BY(x)= \ - SERD_DISABLE_DEPRECATED \ - SERD_NONNULL= \ - SERD_NULLABLE= \ - SERD_PURE_FUNC= - -RECURSIVE = YES -STRIP_FROM_PATH = @SERD_SRCDIR@ -INPUT = @SERD_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 b40af2f1..00000000 --- a/doc/c/api/meson.build +++ /dev/null @@ -1,9 +0,0 @@ -# Copyright 2020-2022 David Robillard -# SPDX-License-Identifier: 0BSD OR ISC - -c_serd_rst = custom_target( - 'serd.rst', - command: [sphinxygen, '-f', '@INPUT0@', '@OUTDIR@'], - input: [c_index_xml] + c_rst_files, - output: 'serd.rst', -) 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 - 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 -# 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/c/overview.rst b/doc/c/overview.rst deleted file mode 100644 index b03615b9..00000000 --- a/doc/c/overview.rst +++ /dev/null @@ -1,26 +0,0 @@ -.. - Copyright 2020-2021 David Robillard - SPDX-License-Identifier: ISC - -######## -Overview -######## - -.. default-domain:: c -.. highlight:: c - -The API revolves around two main types: the :doc:`api/serd_reader`, -which reads text and fires callbacks, -and the :doc:`api/serd_writer`, -which writes text when driven by corresponding functions. -Both work in a streaming fashion but still support pretty-printing, -so the pair can be used to pretty-print, translate, -or otherwise process arbitrarily large documents very quickly. -The context of a stream is tracked by the :doc:`api/serd_env`, -which stores the current base URI and set of namespace prefixes. - -The complete API is declared in ``serd.h``: - -.. code-block:: c - - #include diff --git a/doc/c/xml/meson.build b/doc/c/xml/meson.build deleted file mode 100644 index 34852719..00000000 --- a/doc/c/xml/meson.build +++ /dev/null @@ -1,21 +0,0 @@ -# Copyright 2020-2022 David Robillard -# 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() / '..') - -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 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 +# 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/index.rst b/doc/index.rst new file mode 100644 index 00000000..73e1a5fb --- /dev/null +++ b/doc/index.rst @@ -0,0 +1,20 @@ +.. + Copyright 2020-2023 David Robillard + 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/ +.. _TriG: http://www.w3.org/TR/trig/ 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/overview.rst b/doc/overview.rst new file mode 100644 index 00000000..b03615b9 --- /dev/null +++ b/doc/overview.rst @@ -0,0 +1,26 @@ +.. + Copyright 2020-2021 David Robillard + SPDX-License-Identifier: ISC + +######## +Overview +######## + +.. default-domain:: c +.. highlight:: c + +The API revolves around two main types: the :doc:`api/serd_reader`, +which reads text and fires callbacks, +and the :doc:`api/serd_writer`, +which writes text when driven by corresponding functions. +Both work in a streaming fashion but still support pretty-printing, +so the pair can be used to pretty-print, translate, +or otherwise process arbitrarily large documents very quickly. +The context of a stream is tracked by the :doc:`api/serd_env`, +which stores the current base URI and set of namespace prefixes. + +The complete API is declared in ``serd.h``: + +.. code-block:: c + + #include 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 +# 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/summary.rst b/doc/summary.rst deleted file mode 100644 index 16a236eb..00000000 --- a/doc/summary.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. - Copyright 2020-2021 David Robillard - SPDX-License-Identifier: ISC - -Serd is a lightweight C library for reading and writing RDF in Turtle_, NTriples_, NQuads_, and TriG_. - -.. _Turtle: http://www.w3.org/TR/turtle/ -.. _NTriples: http://www.w3.org/TR/n-triples/ -.. _NQuads: http://www.w3.org/TR/n-quads/ -.. _TriG: http://www.w3.org/TR/trig/ diff --git a/doc/xml/meson.build b/doc/xml/meson.build new file mode 100644 index 00000000..503eff3a --- /dev/null +++ b/doc/xml/meson.build @@ -0,0 +1,19 @@ +# Copyright 2020-2022 David Robillard +# SPDX-License-Identifier: 0BSD OR ISC + +config = configuration_data() +config.set('SERD_SRCDIR', serd_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