From f95f22013d51133ec1a7b1554878ff354b9f0f21 Mon Sep 17 00:00:00 2001
From: David Robillard <d@drobilla.net>
Date: Sun, 20 Dec 2020 20:20:07 +0100
Subject: Generate documentation with Sphinx
---
doc/c/Doxyfile | 33 +++++++++++++++++++++++++++++++++
doc/c/index.rst | 5 +++++
doc/c/overview.rst | 22 ++++++++++++++++++++++
doc/c/reference.rst | 11 +++++++++++
doc/c/wscript | 42 ++++++++++++++++++++++++++++++++++++++++++
5 files changed, 113 insertions(+)
create mode 100644 doc/c/Doxyfile
create mode 100644 doc/c/index.rst
create mode 100644 doc/c/overview.rst
create mode 100644 doc/c/reference.rst
create mode 100644 doc/c/wscript
(limited to 'doc/c')
diff --git a/doc/c/Doxyfile b/doc/c/Doxyfile
new file mode 100644
index 00000000..a88f8ce8
--- /dev/null
+++ b/doc/c/Doxyfile
@@ -0,0 +1,33 @@
+PROJECT_NAME = Serd
+PROJECT_BRIEF = "A lightweight library for RDF storage and serialisation"
+
+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 = SERD_ALLOCATED \
+ SERD_API \
+ SERD_CONST_FUNC= \
+ SERD_DEPRECATED_BY(x)= \
+ SERD_DISABLE_DEPRECATED \
+ SERD_NONNULL= \
+ SERD_NULLABLE= \
+ SERD_PURE_FUNC=
+
+INPUT = ../../include/serd/serd.h
+
+OUTPUT_DIRECTORY = .
diff --git a/doc/c/index.rst b/doc/c/index.rst
new file mode 100644
index 00000000..3fe14ca6
--- /dev/null
+++ b/doc/c/index.rst
@@ -0,0 +1,5 @@
+.. toctree::
+
+ serd
+ overview
+ reference
diff --git a/doc/c/overview.rst b/doc/c/overview.rst
new file mode 100644
index 00000000..95862368
--- /dev/null
+++ b/doc/c/overview.rst
@@ -0,0 +1,22 @@
+########
+Overview
+########
+
+.. default-domain:: c
+.. highlight:: c
+
+The API revolves around two main types: the :doc:`api/reader`,
+which reads text and fires callbacks,
+and the :doc:`api/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/env`,
+which stores the current base URI and set of namespace prefixes.
+
+The complete API is declared in ``serd.h``:
+
+.. code-block:: c
+
+ #include <serd/serd.h>
diff --git a/doc/c/reference.rst b/doc/c/reference.rst
new file mode 100644
index 00000000..70de0603
--- /dev/null
+++ b/doc/c/reference.rst
@@ -0,0 +1,11 @@
+#############
+API Reference
+#############
+
+This section contains the generated documentation for all symbols in the public
+API.
+
+.. toctree::
+
+ api/serd
+
diff --git a/doc/c/wscript b/doc/c/wscript
new file mode 100644
index 00000000..1132f197
--- /dev/null
+++ b/doc/c/wscript
@@ -0,0 +1,42 @@
+#!/usr/bin/env python
+
+def build(bld):
+ dox_to_sphinx = bld.path.find_node("../../scripts/dox_to_sphinx.py")
+ index_xml = bld.path.get_bld().make_node("xml/index.xml")
+
+ files = [
+ ("../../resources/serd.svg", "sphinx/_static/serd.svg"),
+ ("../_static/custom.css", "sphinx/_static/custom.css"),
+ ("../_templates/about.html", "sphinx/_templates/about.html"),
+ ("../serd.rst", "sphinx/serd.rst"),
+ ("index.rst", "sphinx/index.rst"),
+ ("overview.rst", "sphinx/overview.rst"),
+ ("reference.rst", "sphinx/reference.rst"),
+ ]
+
+ # Run Doxygen to generate XML documentation
+ bld(features="doxygen", doxyfile="Doxyfile")
+
+ # Substitute variables to make Sphinx configuration file
+ bld(features="subst",
+ source="../conf.py.in",
+ target="sphinx/conf.py",
+ SERD_VERSION=bld.env.SERD_VERSION)
+
+ # Copy static documentation files to Sphinx build directory
+ for f in files:
+ bld(features="subst", is_copy=True, source=f[0], target=f[1])
+
+ # Generate Sphinx markup from Doxygen XML
+ bld.add_group()
+ bld(rule="${PYTHON} " + dox_to_sphinx.abspath() + " -f ${SRC} ${TGT}",
+ source=index_xml,
+ target="sphinx/api/")
+
+ # Run Sphinx to generate HTML documentation
+ doc_dir = bld.env.DOCDIR + "/serd-%s/" % bld.env.SERD_MAJOR_VERSION
+ bld(features="sphinx",
+ sphinx_source=bld.path.get_bld().make_node("sphinx"),
+ sphinx_output_format="singlehtml",
+ sphinx_options=["-E", "-q"],
+ install_path=doc_dir + "c/singlehtml/")
--
cgit v1.2.1