From f95f22013d51133ec1a7b1554878ff354b9f0f21 Mon Sep 17 00:00:00 2001 From: David Robillard Date: Sun, 20 Dec 2020 20:20:07 +0100 Subject: Generate documentation with Sphinx --- doc/_static/custom.css | 95 ++++++ doc/_templates/about.html | 57 ++++ doc/c/Doxyfile | 33 ++ doc/c/index.rst | 5 + doc/c/overview.rst | 22 ++ doc/c/reference.rst | 11 + doc/c/wscript | 42 +++ doc/conf.py.in | 86 +++++ doc/footer.html | 20 -- doc/header.html | 46 --- doc/index.html.in | 35 -- doc/layout.xml | 194 ----------- doc/mainpage.md | 15 - doc/serd.rst | 11 + doc/style.css | 808 ---------------------------------------------- 15 files changed, 362 insertions(+), 1118 deletions(-) create mode 100644 doc/_static/custom.css create mode 100644 doc/_templates/about.html 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 create mode 100644 doc/conf.py.in delete mode 100644 doc/footer.html delete mode 100644 doc/header.html delete mode 100644 doc/index.html.in delete mode 100644 doc/layout.xml delete mode 100644 doc/mainpage.md create mode 100644 doc/serd.rst delete mode 100644 doc/style.css (limited to 'doc') diff --git a/doc/_static/custom.css b/doc/_static/custom.css new file mode 100644 index 00000000..60aa759e --- /dev/null +++ b/doc/_static/custom.css @@ -0,0 +1,95 @@ +div.document { + margin: 0; +} + +div.body { + margin-top: 2em; +} + +div.sphinxsidebarwrapper { + background: #EEE; +} + +div.sphinxsidebarwrapper p.blurb { + text-align: center; +} + +div.sphinxsidebarwrapper span.logo { + display: block; + text-align: center; + font-family: Georgia, serif; + padding: 0; + font-size: 180%; +} + +div.sphinxsidebar a { + border-width: 0; +} + +div.sphinxsidebar li { + color: #444; +} + +div.section { + margin-top: 2.5em; +} + +a.reference { + border-bottom: none; +} + +code.xref { + font-weight: normal; + background-color: #F8F8F8; + padding: 0.1em 0 0.1em 0; +} + +div.section > dl.c > dt:first-child, +div.section > dl.cpp > dt:first-child { + background-color: #F8F8F8; + font-family: 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace; + font-size: 0.9em; + font-weight: normal; + margin-bottom: 0.5em; + padding: 0.1em 0 0.1em 0; +} + +tt.descname, tt.descclassname, code.descname, code.descclassname { + font-size: 0.9em; +} + +dl.member { + margin-top: 0.5em; +} + +dl.enumerator { + margin-top: 0.5em; +} + +dl.field-list > dt { + padding-left: 0; +} + +pre, tt, code { + background-color: #F8F8F8; +} + +.toctree-l1 { + margin-top: 1.0em; +} + +img.logo { + width: 6em; +} + +.class { + padding-top: 1.5em; +} + +.exception { + padding-top: 1.5em; +} + +.class > dd > dl.function { + padding-top: 1.0em; +} diff --git a/doc/_templates/about.html b/doc/_templates/about.html new file mode 100644 index 00000000..5bbadbe9 --- /dev/null +++ b/doc/_templates/about.html @@ -0,0 +1,57 @@ +{% if theme_logo %} + +{% else %} +

{{ project }}

+{% endif %} + +{% if theme_description %} +

{{ theme_description }}

+{% endif %} + +{% if theme_github_user and theme_github_repo %} +{% if theme_github_button|lower == 'true' %} +

+ +

+{% endif %} +{% endif %} + +{% if theme_travis_button|lower != 'false' %} +{% if theme_travis_button|lower == 'true' %} + {% set path = theme_github_user + '/' + theme_github_repo %} +{% else %} + {% set path = theme_travis_button %} +{% endif %} +

+ + https://secure.travis-ci.org/{{ path }}.svg?branch={{ theme_badge_branch }} + +

+{% endif %} + +{% if theme_codecov_button|lower != 'false' %} +{% if theme_codecov_button|lower == 'true' %} + {% set path = theme_github_user + '/' + theme_github_repo %} +{% else %} + {% set path = theme_codecov_button %} +{% endif %} +

+ + https://codecov.io/github/{{ path }}/coverage.svg?branch={{ theme_badge_branch }} + +

+{% endif %} 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 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/") diff --git a/doc/conf.py.in b/doc/conf.py.in new file mode 100644 index 00000000..224b6e77 --- /dev/null +++ b/doc/conf.py.in @@ -0,0 +1,86 @@ +# Project information + +project = "Serd" +copyright = "2020, David Robillard" +author = "David Robillard" +release = "@SERD_VERSION@" + +# General configuration + +language = "en" + +extensions = [ + # 'sphinx_rtd_theme', +] + +# Enable nitpicky mode to get warnings about broken links +# Unfortunately this means we need to explicitly ignore everything external +nitpicky = True +_opaque = [ + "FILE", + "SerdByteSinkImpl", + "SerdByteSourceImpl", + "SerdCursorImpl", + "SerdEnvImpl", + "SerdIterImpl", + "SerdModelImpl", + "SerdNodeImpl", + "SerdNodesImpl", + "SerdRangeImpl", + "SerdReaderImpl", + "SerdSinkImpl", + "SerdStatementImpl", + "SerdWorldImpl", + "SerdWriterImpl", + "int64_t", + "size_t", + "uint32_t", + "uint8_t", + "uintptr_t", + "va_list", +] + +nitpick_ignore = list(map(lambda x: ("c:identifier", x), _opaque)) + +templates_path = ["_templates"] + +pygments_style = "friendly" + +# HTML output + +exclude_patterns = ["xml"] +html_static_path = ["_static"] + +html_theme = "alabaster" +# html_theme = "sphinx_rtd_theme" + +if html_theme == "alabaster": + + html_theme_options = { + "description": "A lightweight library for RDF storage and serialisation", + "donate_url": "http://drobilla.net/pages/donate.html", + # "github_repo": "serd", + # "github_user": "lv2", + "logo": "serd.svg", + "logo_name": True, + "logo_text_align": "center", + "page_width": "80em - 20em", + "sidebar_width": "24em", + } + + html_sidebars = { + "**": [ + "about.html", + "localtoc.html", + "donate.html", + ] + } + +elif html_theme == "sphinx_rtd_theme": + + html_theme_options = { + "sticky_navigation": False, + "collapse_navigation": False, + "navigation_depth": 4, + "display_version": True, + } diff --git a/doc/footer.html b/doc/footer.html deleted file mode 100644 index 0dc69197..00000000 --- a/doc/footer.html +++ /dev/null @@ -1,20 +0,0 @@ - - - - - - - - - - diff --git a/doc/header.html b/doc/header.html deleted file mode 100644 index b907bc8b..00000000 --- a/doc/header.html +++ /dev/null @@ -1,46 +0,0 @@ - - - - - $projectname: $title - $title - - $extrastylesheet - - -
- - -
- -
- - - - - diff --git a/doc/index.html.in b/doc/index.html.in deleted file mode 100644 index 55d2d1e7..00000000 --- a/doc/index.html.in +++ /dev/null @@ -1,35 +0,0 @@ - - - - - Serd - - - -
-
- -
- - - - - -