diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/_static/custom.css | 16 | ||||
| -rw-r--r-- | doc/c/meson.build | 24 | ||||
| -rw-r--r-- | doc/conf.py.in | 53 |
3 files changed, 75 insertions, 18 deletions
diff --git a/doc/_static/custom.css b/doc/_static/custom.css new file mode 100644 index 00000000..757c218c --- /dev/null +++ b/doc/_static/custom.css @@ -0,0 +1,16 @@ +/* Copyright 2022 David Robillard <d@drobilla.net> */ +/* SPDX-License-Identifier: 0BSD or ISC */ + +div.bodywrapper { + margin: 0 0 0 16em; +} + +section > dl { + margin-bottom: 30px; +} + +.struct > dd > dl.member > dt, +.enum > dd > dl.member > dt, +.enum-class > dd > dl.member > dt { + padding: 15px 0 0; +} diff --git a/doc/c/meson.build b/doc/c/meson.build index a2f7eaa5..8c4934de 100644 --- a/doc/c/meson.build +++ b/doc/c/meson.build @@ -1,6 +1,20 @@ # Copyright 2020-2022 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 + config = configuration_data() config.set('SERD_VERSION', meson.project_version()) config.set('SERD_SRCDIR', serd_src_root) @@ -12,6 +26,8 @@ conf_py = configure_file( output: 'conf.py', ) +# Copy hand-written documentation sources + configure_file( copy: true, input: files('../summary.rst'), @@ -27,9 +43,13 @@ 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 + # TODO: Add install_tag: 'doc' after requiring meson 0.60.0 custom_target( @@ -37,7 +57,7 @@ custom_target( build_by_default: true, command: [sphinx_build, '-M', 'singlehtml', '@OUTDIR@', '@OUTDIR@', '-E', '-q', '-t', 'singlehtml'], - input: [c_rst_files, c_serd_rst, c_index_xml], + input: [c_rst_files, c_serd_rst, c_index_xml, conf_py], install: true, install_dir: docdir / versioned_name, output: 'singlehtml', @@ -48,7 +68,7 @@ custom_target( build_by_default: true, command: [sphinx_build, '-M', 'html', '@OUTDIR@', '@OUTDIR@', '-E', '-q', '-t', 'html'], - input: [c_rst_files, c_serd_rst, c_index_xml], + input: [c_rst_files, c_serd_rst, c_index_xml, conf_py], install: true, install_dir: docdir / versioned_name, output: 'html', diff --git a/doc/conf.py.in b/doc/conf.py.in index 7b3e8ee1..924066aa 100644 --- a/doc/conf.py.in +++ b/doc/conf.py.in @@ -7,6 +7,8 @@ project = "@SERD_TITLE@" copyright = "2022, David Robillard" author = "David Robillard" release = "@SERD_VERSION@" +version = "@SERD_VERSION@" +desc = "A lightweight library for working with RDF" # General configuration @@ -17,6 +19,7 @@ pygments_style = "friendly" try: import sphinx_lv2_theme + have_lv2_theme = True except ModuleNotFoundError: have_lv2_theme = False @@ -51,14 +54,14 @@ nitpick_ignore = list(map(lambda x: ("c:identifier", x), _opaque)) # HTML output html_copy_source = False +html_secnumber_suffix = " " html_short_title = "@SERD_TITLE@" html_static_path = ["@SERD_SRCDIR@/doc/_static"] -html_theme = "sphinx_lv2_theme" if have_lv2_theme: html_theme = "sphinx_lv2_theme" - if tags.has('singlehtml'): + if tags.has("singlehtml"): html_sidebars = { "**": [ "globaltoc.html", @@ -68,7 +71,7 @@ if have_lv2_theme: html_theme_options = { "body_max_width": "48em", "body_min_width": "48em", - "description": "A lightweight library for working with RDF", + "description": desc, "show_footer_version": True, "show_logo_version": False, "logo": "serd.svg", @@ -76,7 +79,7 @@ if have_lv2_theme: "logo_width": "8em", "nosidebar": False, "page_width": "80em", - "sidebar_width": "18em", + "sidebar_width": "12em", "globaltoc_maxdepth": 3, "globaltoc_collapse": False, } @@ -85,7 +88,7 @@ if have_lv2_theme: html_theme_options = { "body_max_width": "60em", "body_min_width": "40em", - "description": "A lightweight library for working with RDF", + "description": desc, "show_footer_version": True, "show_logo_version": False, "logo": "serd.svg", @@ -102,14 +105,32 @@ else: html_theme = "alabaster" - html_theme_options = { - "body_max_width": "60em", - "body_min_width": "40em", - "description": "A lightweight library for working with RDF", - "logo": "serd.svg", - "logo_name": True, - "page_width": "60em", - "sidebar_width": "14em", - "globaltoc_maxdepth": 1, - "globaltoc_collapse": True, - } + if tags.has("singlehtml"): + html_sidebars = { + "**": [ + "globaltoc.html", + ] + } + + html_theme_options = { + "body_max_width": "40em", + "body_min_width": "40em", + "description": desc, + "globaltoc_collapse": False, + "globaltoc_maxdepth": 3, + "logo": "serd.svg", + "nosidebar": False, + "page_width": "56em", + "sidebar_width": "16em", + } + + 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, + } |