aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorDavid Robillard <d@drobilla.net>2021-01-06 21:50:05 +0100
committerDavid Robillard <d@drobilla.net>2021-01-06 21:50:05 +0100
commitf2adb0c2050512c643013481dd6f53d8a3fcb163 (patch)
treec5d6ac71e88fba74cc17e1e4ccf2eddeee07ebfa
parenta6fa6c45a4df2e0a15ce40437fb03063c9c68891 (diff)
downloadserd-f2adb0c2050512c643013481dd6f53d8a3fcb163.tar.gz
serd-f2adb0c2050512c643013481dd6f53d8a3fcb163.tar.bz2
serd-f2adb0c2050512c643013481dd6f53d8a3fcb163.zip
Switch to LV2 documentation theme
-rw-r--r--.gitlab-ci.yml1
-rw-r--r--README.md3
-rw-r--r--doc/_static/custom.css95
-rw-r--r--doc/_templates/about.html57
-rw-r--r--doc/c/index.rst9
-rw-r--r--doc/c/wscript19
-rw-r--r--doc/conf.py.in75
-rw-r--r--doc/summary.rst (renamed from doc/serd.rst)7
-rw-r--r--include/serd/serd.h4
9 files changed, 60 insertions, 210 deletions
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 <d@drobilla.net>
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 %}
-<p class="logo">
- <a href="{{ pathto(master_doc) }}">
- <img class="logo" src="{{ pathto('_static/' ~ theme_logo, 1) }}" alt="Logo"/>
- {% if theme_logo_name|lower == 'true' %}
- <span class="logo logo-name">{{ project }}</span>
- {% endif %}
- </a>
-</p>
-{% else %}
-<h1 class="logo"><a href="{{ pathto(master_doc) }}">{{ project }}</a></h1>
-{% endif %}
-
-{% if theme_description %}
-<p class="blurb">{{ theme_description }}</p>
-{% endif %}
-
-{% if theme_github_user and theme_github_repo %}
-{% if theme_github_button|lower == 'true' %}
-<p>
-<iframe src="https://ghbtns.com/github-btn.html?user={{ theme_github_user }}&repo={{ theme_github_repo }}&type={{ theme_github_type }}&count={{ theme_github_count }}&size=large&v=2"
- allowtransparency="true" frameborder="0" scrolling="0" width="200px" height="35px"></iframe>
-</p>
-{% 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 %}
-<p>
-<a class="badge" href="https://travis-ci.org/{{ path }}">
- <img
- alt="https://secure.travis-ci.org/{{ path }}.svg?branch={{ theme_badge_branch }}"
- src="https://secure.travis-ci.org/{{ path }}.svg?branch={{ theme_badge_branch }}"
- />
-</a>
-</p>
-{% 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 %}
-<p>
-<a class="badge" href="https://codecov.io/github/{{ path }}">
- <img
- alt="https://codecov.io/github/{{ path }}/coverage.svg?branch={{ theme_badge_branch }}"
- src="https://codecov.io/github/{{ path }}/coverage.svg?branch={{ theme_badge_branch }}"
- />
-</a>
-</p>
-{% 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/summary.rst
index e90a8368..4b8d6e4e 100644
--- a/doc/serd.rst
+++ b/doc/summary.rst
@@ -1,9 +1,4 @@
-####
-Serd
-####
-
-Serd is a lightweight and dependency-free C library for RDF serialisation which
-supports Turtle_, NTriples_, NQuads_, and TriG_.
+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/
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.
@{
*/