From f2adb0c2050512c643013481dd6f53d8a3fcb163 Mon Sep 17 00:00:00 2001 From: David Robillard Date: Wed, 6 Jan 2021 21:50:05 +0100 Subject: Switch to LV2 documentation theme --- .gitlab-ci.yml | 1 + README.md | 3 +- doc/_static/custom.css | 95 ----------------------------------------------- doc/_templates/about.html | 57 ---------------------------- doc/c/index.rst | 9 ++++- doc/c/wscript | 19 +++++----- doc/conf.py.in | 75 +++++++++++++++++++------------------ doc/serd.rst | 11 ------ doc/summary.rst | 6 +++ include/serd/serd.h | 4 +- 10 files changed, 65 insertions(+), 215 deletions(-) delete mode 100644 doc/_static/custom.css delete mode 100644 doc/_templates/about.html delete mode 100644 doc/serd.rst create mode 100644 doc/summary.rst diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 3f50493d..2e34f9d3 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -220,6 +220,7 @@ pages: - mkdir -p .public/man - mkdir -p .public/c - mv build/doc/c/singlehtml .public/c/singlehtml + - mv build/doc/c/html .public/c/html - mv build/doc/serdi.html .public/man/serdi.html - mv .public public artifacts: diff --git a/README.md b/README.md index 73ab5ead..fb3dd78a 100644 --- a/README.md +++ b/README.md @@ -48,7 +48,8 @@ constant amount of memory (a single page) for all input sizes. Documentation ------------- - * [API reference](https://drobilla.gitlab.io/serd/c/singlehtml) + * [API reference (single page)](https://drobilla.gitlab.io/serd/c/singlehtml) + * [API reference (paginated)](https://drobilla.gitlab.io/serd/c/html) * [`serdi` man page](https://drobilla.gitlab.io/serd/man/serdi.html) -- David Robillard diff --git a/doc/_static/custom.css b/doc/_static/custom.css deleted file mode 100644 index 60aa759e..00000000 --- a/doc/_static/custom.css +++ /dev/null @@ -1,95 +0,0 @@ -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 deleted file mode 100644 index 5bbadbe9..00000000 --- a/doc/_templates/about.html +++ /dev/null @@ -1,57 +0,0 @@ -{% 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/index.rst b/doc/c/index.rst index 3fe14ca6..fe14fc3b 100644 --- a/doc/c/index.rst +++ b/doc/c/index.rst @@ -1,5 +1,10 @@ +#### +Serd +#### + +.. include:: summary.rst + .. toctree:: - serd overview - reference + api/serd diff --git a/doc/c/wscript b/doc/c/wscript index 1132f197..9a524e3a 100644 --- a/doc/c/wscript +++ b/doc/c/wscript @@ -6,12 +6,9 @@ def build(bld): 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"), + ("../summary.rst", "sphinx/summary.rst"), ("index.rst", "sphinx/index.rst"), ("overview.rst", "sphinx/overview.rst"), - ("reference.rst", "sphinx/reference.rst"), ] # Run Doxygen to generate XML documentation @@ -33,10 +30,12 @@ def build(bld): 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/") + + # Run Sphinx to generate HTML documentation + for builder in ["html", "singlehtml"]: + bld(features="sphinx", + sphinx_source=bld.path.get_bld().make_node("sphinx"), + sphinx_output_format=builder, + sphinx_options=["-E", "-q", "-t", builder], + install_path=doc_dir + "c/%s/" % builder) diff --git a/doc/conf.py.in b/doc/conf.py.in index aa98c01a..170ae1b1 100644 --- a/doc/conf.py.in +++ b/doc/conf.py.in @@ -7,15 +7,12 @@ release = "@SERD_VERSION@" # General configuration +exclude_patterns = ["xml"] 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 +pygments_style = "friendly" + +# Ignore everything opaque or external for nitpicky mode _opaque = [ "FILE", "SerdByteSinkImpl", @@ -42,45 +39,49 @@ _opaque = [ 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 = "sphinx_lv2_theme" +html_copy_source = False +html_short_title = "Serd" -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 - 24em", - "sidebar_width": "24em", - } - +if tags.has('singlehtml'): html_sidebars = { "**": [ - "about.html", - "localtoc.html", - "donate.html", + "globaltoc.html", ] } -elif html_theme == "sphinx_rtd_theme": + html_theme_options = { + "body_max_width": "48em", + "body_min_width": "48em", + "description": "A lightweight library for working with RDF", + "show_footer_version": True, + "show_logo_version": False, + "logo": "serd.svg", + "logo_name": True, + "logo_width": "8em", + "nosidebar": False, + "page_width": "80em", + "sidebar_width": "18em", + "globaltoc_maxdepth": 3, + "globaltoc_collapse": False, + } +else: html_theme_options = { - "sticky_navigation": False, - "collapse_navigation": False, - "navigation_depth": 4, - "display_version": True, + "body_max_width": "60em", + "body_min_width": "40em", + "description": "A lightweight library for working with RDF", + "show_footer_version": True, + "show_logo_version": False, + "logo": "serd.svg", + "logo_name": True, + "logo_width": "8em", + "nosidebar": True, + "page_width": "60em", + "sidebar_width": "14em", + "globaltoc_maxdepth": 1, + "globaltoc_collapse": True, } diff --git a/doc/serd.rst b/doc/serd.rst deleted file mode 100644 index e90a8368..00000000 --- a/doc/serd.rst +++ /dev/null @@ -1,11 +0,0 @@ -#### -Serd -#### - -Serd is a lightweight and dependency-free C library for RDF serialisation which -supports Turtle_, NTriples_, NQuads_, and TriG_. - -.. _Turtle: http://www.w3.org/TR/turtle/ -.. _NTriples: http://www.w3.org/TR/n-triples/ -.. _NQuads: http://www.w3.org/TR/n-quads/ -.. _TriG: http://www.w3.org/TR/trig/ diff --git a/doc/summary.rst b/doc/summary.rst new file mode 100644 index 00000000..4b8d6e4e --- /dev/null +++ b/doc/summary.rst @@ -0,0 +1,6 @@ +Serd is a lightweight C library for reading and writing RDF in Turtle_, NTriples_, NQuads_, and TriG_. + +.. _Turtle: http://www.w3.org/TR/turtle/ +.. _NTriples: http://www.w3.org/TR/n-triples/ +.. _NQuads: http://www.w3.org/TR/n-quads/ +.. _TriG: http://www.w3.org/TR/trig/ diff --git a/include/serd/serd.h b/include/serd/serd.h index 8eb29876..9265bb54 100644 --- a/include/serd/serd.h +++ b/include/serd/serd.h @@ -82,8 +82,8 @@ extern "C" { #endif /** - @defgroup serd Serd - A lightweight RDF syntax library. + @defgroup serd Serd C API + This is the complete public C API of serd. @{ */ -- cgit v1.2.1