Build reference documentation

11 files changed, 423 insertions, 0 deletions

diff --git a/doc/.clang-tidy b/doc/.clang-tidy
new file mode 100644
index 0000000..3d0f771
--- /dev/null
+++ b/doc/.clang-tidy
@@ -0,0 +1,11 @@
+# Copyright 2020-2022 David Robillard <d@drobilla.net>
+# SPDX-License-Identifier: 0BSD OR ISC
+
+Checks: >
+  *,
+  -altera-*,
+  -clang-analyzer-deadcode.DeadStores,
+  -llvmlibc-*,
+WarningsAsErrors: '*'
+HeaderFilterRegex: '.*'
+FormatStyle: file
diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in
new file mode 100644
index 0000000..52f6dda
--- /dev/null
+++ b/doc/Doxyfile.in
@@ -0,0 +1,72 @@
+# Copyright 2021-2022 David Robillard <d@drobilla.net>
+# SPDX-License-Identifier: 0BSD OR ISC
+
+PROJECT_NAME           = Zix
+PROJECT_BRIEF          = "A lightweight C library of portability wrappers and data structures"
+
+QUIET                  = YES
+WARN_AS_ERROR          = YES
+WARN_IF_UNDOCUMENTED   = YES
+WARN_NO_PARAMDOC       = NO
+
+RECURSIVE=YES
+
+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
+
+
+EXPAND_ONLY_PREDEF     = YES
+MACRO_EXPANSION        = YES
+SKIP_FUNCTION_MACROS   = NO
+PREDEFINED             = ZIX_ALLOCATED= \
+                         ZIX_ALWAYS_INLINE_FUNC= \
+                         ZIX_API= \
+                         ZIX_BEGIN_DECLS= \
+                         ZIX_CONST_API= \
+                         ZIX_CONST_FUNC= \
+                         ZIX_END_DECLS= \
+                         ZIX_MALLOC_API= \
+                         ZIX_MALLOC_FUNC= \
+                         ZIX_NONNULL= \
+                         ZIX_NULLABLE= \
+                         ZIX_PURE_API= \
+                         ZIX_PURE_FUNC= \
+                         ZIX_PURE_WIN_API= \
+                         ZIX_THREAD_FUNC= \
+
+STRIP_FROM_PATH        = @ZIX_SRCDIR@
+INPUT                  = @ZIX_SRCDIR@/include/zix/zix.h \
+                         \
+                         @ZIX_SRCDIR@/include/zix/attributes.h \
+                         @ZIX_SRCDIR@/include/zix/status.h \
+                         @ZIX_SRCDIR@/include/zix/string_view.h \
+                         \
+                         @ZIX_SRCDIR@/include/zix/allocator.h \
+                         @ZIX_SRCDIR@/include/zix/bump_allocator.h \
+                         \
+                         @ZIX_SRCDIR@/include/zix/digest.h \
+                         @ZIX_SRCDIR@/include/zix/function_types.h \
+                         \
+                         @ZIX_SRCDIR@/include/zix/bitset.h \
+                         @ZIX_SRCDIR@/include/zix/btree.h \
+                         @ZIX_SRCDIR@/include/zix/hash.h \
+                         @ZIX_SRCDIR@/include/zix/ring.h \
+                         @ZIX_SRCDIR@/include/zix/tree.h \
+                         \
+                         @ZIX_SRCDIR@/include/zix/sem.h \
+                         @ZIX_SRCDIR@/include/zix/thread.h \
+                         \
+                         @ZIX_SRCDIR@/include/zix/filesystem.h \
+                         @ZIX_SRCDIR@/include/zix/path.h \
+
+OUTPUT_DIRECTORY       = @DOX_OUTPUT@
diff --git a/doc/api/meson.build b/doc/api/meson.build
new file mode 100644
index 0000000..b6a1adb
--- /dev/null
+++ b/doc/api/meson.build
@@ -0,0 +1,9 @@
+# Copyright 2021 David Robillard <d@drobilla.net>
+# SPDX-License-Identifier: 0BSD OR ISC
+
+c_zix_rst = custom_target(
+  'zix.rst',
+  command: [dox_to_sphinx, '-f', '@INPUT0@', '@OUTDIR@'],
+  input: [c_index_xml] + c_rst_files,
+  output: 'zix.rst',
+)
diff --git a/doc/conf.py b/doc/conf.py
new file mode 100644
index 0000000..e8a057c
--- /dev/null
+++ b/doc/conf.py
@@ -0,0 +1,95 @@
+# Copyright 2021-2022 David Robillard <d@drobilla.net>
+# SPDX-License-Identifier: 0BSD OR ISC
+
+# Project information
+
+project = "Zix"
+copyright = "2011-2022, David Robillard"
+author = "David Robillard"
+release = "dev"
+desc = "A lightweight C library of portability wrappers and data structures"
+
+# General configuration
+
+exclude_patterns = ["xml"]
+language = "en"
+nitpicky = True
+pygments_style = "friendly"
+
+# Ignore everything opaque or external for nitpicky mode
+_opaque = [
+    "FILE",
+    "ZixAllocator",
+    "ZixAllocatorImpl",
+    "ZixBTree",
+    "ZixBTreeImpl",
+    "ZixBTreeNode",
+    "ZixBTreeNodeImpl",
+    "ZixHash",
+    "ZixHashImpl",
+    "ZixRing",
+    "ZixRingImpl",
+    "ZixSem",
+    "ZixSemImpl",
+    "ZixTree",
+    "ZixTreeImpl",
+    "ZixTreeIter",
+    "ZixTreeNode",
+    "ZixTreeNodeImpl",
+    "int64_t",
+    "pthread_t",
+    "ptrdiff_t",
+    "size_t",
+    "uint16_t",
+    "uint32_t",
+    "uint64_t",
+    "uint8_t",
+]
+
+_c_nitpick_ignore = map(lambda x: ("c:identifier", x), _opaque)
+_cpp_nitpick_ignore = map(lambda x: ("cpp:identifier", x), _opaque)
+nitpick_ignore = list(_c_nitpick_ignore) + list(_cpp_nitpick_ignore)
+
+# HTML output
+
+html_copy_source = False
+html_short_title = "Zix"
+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,
+        "show_footer_version": True,
+        "show_logo_version": True,
+        "logo_name": True,
+        "logo_width": "8em",
+        "nosidebar": False,
+        "page_width": "80em",
+        "sidebar_width": "18em",
+        "globaltoc_maxdepth": 3,
+        "globaltoc_collapse": False,
+    }
+
+else:
+    html_theme_options = {
+        "body_max_width": "60em",
+        "body_min_width": "40em",
+        "description": desc,
+        "show_footer_version": True,
+        "show_logo_version": True,
+        "logo_name": True,
+        "logo_width": "8em",
+        "nosidebar": True,
+        "page_width": "60em",
+        "sidebar_width": "14em",
+        "globaltoc_maxdepth": 1,
+        "globaltoc_collapse": True,
+    }
diff --git a/doc/index.rst b/doc/index.rst
new file mode 100644
index 0000000..56062e6
--- /dev/null
+++ b/doc/index.rst
@@ -0,0 +1,15 @@
+..
+   Copyright 2020-2022 David Robillard <d@drobilla.net>
+   SPDX-License-Identifier: ISC
+
+###
+Zix
+###
+
+.. include:: summary.rst
+
+.. toctree::
+   :numbered:
+
+   using_zix
+   api/zix
diff --git a/doc/meson.build b/doc/meson.build
new file mode 100644
index 0000000..f406624
--- /dev/null
+++ b/doc/meson.build
@@ -0,0 +1,78 @@
+# Copyright 2021-2022 David Robillard <d@drobilla.net>
+# SPDX-License-Identifier: 0BSD OR ISC
+
+docdir = get_option('datadir') / 'doc'
+
+doxygen = find_program('doxygen', required: get_option('docs'))
+dox_to_sphinx = find_program('../scripts/dox_to_sphinx.py')
+sphinx_build = find_program('sphinx-build', required: get_option('docs'))
+
+build_docs = doxygen.found() and sphinx_build.found()
+if build_docs
+
+  # Documentation Code
+
+  test(
+    'overview_code',
+    executable(
+      'overview_code',
+      files('overview_code.c'),
+      dependencies: [zix_dep],
+      c_args: c_suppressions,
+    )
+  )
+
+  # Generated API Reference
+
+  c_rst_files = files(
+    'index.rst',
+    'string_views.rst',
+    'summary.rst',
+    'using_zix.rst',
+  )
+
+  c_doc_files = c_rst_files + files(
+    'conf.py',
+    'overview_code.c',
+  )
+
+  foreach f : c_doc_files
+    configure_file(copy: true, input: f, output: '@PLAINNAME@')
+  endforeach
+
+  subdir('xml')
+  subdir('api')
+
+  sphinx_options = [
+    '-D', 'release=@0@'.format(meson.project_version()),
+    '-E',
+    '-W',
+    '-a',
+    '-q',
+  ]
+
+  doc_inputs = c_rst_files + [c_zix_rst, c_index_xml]
+
+  custom_target(
+    'singlehtml',
+    build_by_default: true,
+    command: [sphinx_build, '-M', 'singlehtml', '@OUTDIR@', '@OUTDIR@',
+              '-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@',
+              '-t', 'html'] + sphinx_options,
+    input: doc_inputs,
+    install: true,
+    install_dir: docdir / versioned_name,
+    output: 'html',
+  )
+
+endif
diff --git a/doc/overview_code.c b/doc/overview_code.c
new file mode 100644
index 0000000..1370292
--- /dev/null
+++ b/doc/overview_code.c
@@ -0,0 +1,51 @@
+// Copyright 2021-2022 David Robillard <d@drobilla.net>
+// SPDX-License-Identifier: ISC
+
+/*
+  Example code that is included in the documentation.  Code in the
+  documentation is included from here rather than written inline so that it can
+  be tested and avoid rotting.  The code here doesn't make much sense, but is
+  written such that it at least compiles and will run without crashing.
+*/
+
+#include "zix/attributes.h"
+#include "zix/string_view.h"
+
+#if defined(__GNUC__)
+#  pragma GCC diagnostic push
+#  pragma GCC diagnostic ignored "-Wunused-variable"
+#endif
+
+static void
+string_views(void)
+{
+  const char* const string_pointer = "some string";
+
+  // begin make-empty-string
+  ZixStringView empty = zix_empty_string();
+  // end make-empty-string
+
+  // begin make-static-string
+  ZixStringView hello = zix_string("hello");
+  // end make-static-string
+
+  // begin measure-string
+  ZixStringView view = zix_string(string_pointer);
+  // end measure-string
+
+  // begin make-string-view
+  ZixStringView slice = zix_substring(string_pointer, 4);
+  // end make-string-view
+}
+
+ZIX_CONST_FUNC
+int
+main(void)
+{
+  string_views();
+  return 0;
+}
+
+#if defined(__GNUC__)
+#  pragma GCC diagnostic pop
+#endif
diff --git a/doc/string_views.rst b/doc/string_views.rst
new file mode 100644
index 0000000..b6e3fd9
--- /dev/null
+++ b/doc/string_views.rst
@@ -0,0 +1,56 @@
+..
+   Copyright 2020-2022 David Robillard <d@drobilla.net>
+   SPDX-License-Identifier: ISC
+
+String Views
+============
+
+.. default-domain:: c
+.. highlight:: c
+
+For performance reasons,
+many functions in zix that take a string take a :struct:`ZixStringView`,
+rather than a bare pointer.
+This forces code to be explicit about string measurement,
+which discourages common patterns of repeated measurement of the same string.
+For convenience, several macros and functions are provided for constructing string views:
+
+:func:`zix_empty_string`
+
+   Constructs a view of an empty string, for example:
+
+   .. literalinclude:: overview_code.c
+      :start-after: begin make-empty-string
+      :end-before: end make-empty-string
+      :dedent: 2
+
+:func:`zix_string`
+
+   Constructs a view of an arbitrary string, for example:
+
+   .. literalinclude:: overview_code.c
+      :start-after: begin measure-string
+      :end-before: end measure-string
+      :dedent: 2
+
+   This calls ``strlen`` to measure the string.
+   Modern compilers should optimize this away if the parameter is a literal.
+
+:func:`zix_substring`
+
+   Constructs a view of a slice of a string with an explicit length,
+   for example:
+
+   .. literalinclude:: overview_code.c
+      :start-after: begin make-string-view
+      :end-before: end make-string-view
+      :dedent: 2
+
+   This can also be used to create a view of a pre-measured string.
+   If the length a dynamic string is already known,
+   this is faster than :func:`zix_string`,
+   since it avoids redundant measurement.
+
+These constructors can be used inline when passing parameters,
+but if the same dynamic string is used several times,
+it is better to make a string view variable to avoid redundant measurement.
diff --git a/doc/summary.rst b/doc/summary.rst
new file mode 100644
index 0000000..aa169df
--- /dev/null
+++ b/doc/summary.rst
@@ -0,0 +1,5 @@
+..
+   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/doc/using_zix.rst b/doc/using_zix.rst
new file mode 100644
index 0000000..f97ecf0
--- /dev/null
+++ b/doc/using_zix.rst
@@ -0,0 +1,12 @@
+..
+   Copyright 2020-2022 David Robillard <d@drobilla.net>
+   SPDX-License-Identifier: ISC
+
+##########
+Using Zix
+##########
+
+.. toctree::
+
+   string_views
+
diff --git a/doc/xml/meson.build b/doc/xml/meson.build
new file mode 100644
index 0000000..b614580
--- /dev/null
+++ b/doc/xml/meson.build
@@ -0,0 +1,19 @@
+# Copyright 2021-2022 David Robillard <d@drobilla.net>
+# SPDX-License-Identifier: 0BSD OR ISC
+
+config = configuration_data()
+config.set('ZIX_SRCDIR', zix_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',
+)