diff options
Diffstat (limited to 'doc/c')
| -rw-r--r-- | doc/c/Doxyfile | 33 | ||||
| -rw-r--r-- | doc/c/index.rst | 5 | ||||
| -rw-r--r-- | doc/c/overview.rst | 22 | ||||
| -rw-r--r-- | doc/c/reference.rst | 11 | ||||
| -rw-r--r-- | doc/c/wscript | 42 |
5 files changed, 113 insertions, 0 deletions
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/") |