doc: switch to furo theme

- add logo for branding in favicon and nav menu title
- remove all `.. contents::` directives as they're redundant in the furo theme (ToC has an independent menu)
- uniform some theme elements' colors (via custom CSS) to match the blue in breathe-doc.org

documentation/source/_static/breathe.css

@@ -1,4 +1,3 @@
-
 /* -- breathe specific styles ----------------------------------------------- */
 
 /* So enum value descriptions are displayed inline to the item */
@@ -10,3 +9,105 @@
 .breatheparameterlist li tt + p {
   display: inline;
 }
+
+:root {
+  --color-brand-primary-light: hsl(205deg, 52%, 39%);
+  --color-brand-primary-dark: hsl(205deg, 65%, 65%);
+  --breathe-str-char-color-dark: hsl(41, 85%, 46%);
+  --breathe-str-char-color-light: hsl(41, 89%, 37%);
+  --breathe-keyword-type-color-dark: hsl(256, 100%, 65%);
+  --breathe-keyword-type-color-light: hsl(276, 85%, 29%);
+  --breathe-number-color-dark: hsl(157, 81%, 50%);
+  --breathe-number-color-light: hsl(157, 93%, 32%);
+  --breathe-name-color-dark: hsl(88, 72%, 56%);
+  --breathe-name-color-light: hsl(88, 100%, 28%);
+}
+
+/* ************************************************** */
+/* rules to uniform color scheme with breathe-doc.org */
+
+body {
+  --color-brand-primary: var(--color-brand-primary-light);
+  --color-brand-content: var(--color-brand-primary-light);
+  --breathe-str-char-color: var(--breathe-str-char-color-light);
+  --breathe-keyword-type-color: var(--breathe-keyword-type-color-light);
+  --breathe-number-color: var(--breathe-number-color-light);
+  --breathe-name-color: var(--breathe-name-color-light);
+}
+
+/* Enable dark-mode, if requested. */
+body[data-theme="dark"] {
+  --color-brand-primary: var(--color-brand-primary-dark);
+  --color-brand-content: var(--color-brand-primary-dark);
+  --breathe-str-char-color: var(--breathe-str-char-color-dark);
+  --breathe-keyword-type-color: var(--breathe-keyword-type-color-dark);
+  --breathe-number-color: var(--breathe-number-color-dark);
+  --breathe-name-color: var(--breathe-name-color-dark);
+}
+
+/* Enable dark mode, unless explicitly told to avoid. */
+@media (prefers-color-scheme: dark) {
+  body:not([data-theme="light"]) {
+    --color-brand-primary: var(--color-brand-primary-dark);
+    --color-brand-content: var(--color-brand-primary-dark);
+    --breathe-str-char-color: var(--breathe-str-char-color-dark);
+    --breathe-keyword-type-color: var(--breathe-keyword-type-color-dark);
+    --breathe-number-color: var(--breathe-number-color-dark);
+    --breathe-name-color: var(--breathe-name-color-dark);
+  }
+}
+
+.mobile-header {
+  /* background-color: var(--color-header-background); */
+  background-color: #003c66;
+}
+
+.mobile-header .toc-overlay-icon .icon {
+  /* color: var(--color-foreground-secondary); */
+  color: white;
+}
+
+.mobile-header .header-center a {
+  /* color: var(--color-header-text); */
+  color: white;
+}
+
+.mobile-header .theme-toggle svg {
+  /* color: var(--color-foreground-primary); */
+  color: white;
+}
+
+/* C++ specific styling */
+
+.highlight {
+  /* desaturate that ugly yellow color used by most other theme's code snippets */
+  background-color: var(--color-api-background); /* for light theme only */
+}
+
+.sig.c   .k, .sig.c   .kt,
+.sig.cpp .k, .sig.cpp .kt {
+  color: var(--breathe-keyword-type-color);
+}
+
+.sig.c   .m,
+.sig.cpp .m {
+  color: var(--breathe-number-color);
+}
+
+.sig.c   .s, .sig.c   .sc,
+.sig.cpp .s, .sig.cpp .sc {
+  color: var(--breathe-str-char-color);
+}
+
+.sig > .n {
+  color: var(--breathe-name-color);
+}
+
+/*
+bugfix for multi-lined signatures
+(see https://github.com/pradyunsg/furo/discussions/427 )
+*/
+.sig {
+  padding-left: 0.5em;
+  text-indent: revert;
+}

documentation/source/_static/logo.svg

@@ -0,0 +1,49 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+<svg width="500" height="500" version="1.1" viewBox="0 0 132.29 132.29" xmlns="http://www.w3.org/2000/svg">
+ <defs>
+  <linearGradient id="linearGradient863" x1="60.598" x2="60.598" y1="130.21" y2="24.658" gradientUnits="userSpaceOnUse">
+   <stop stop-color="#4782ae" offset="0"/>
+   <stop stop-color="#d6e5ef" offset="1"/>
+  </linearGradient>
+ </defs>
+ <g transform="matrix(.96854 0 0 .96859 2.7506 -.28411)" stroke-width="1.0325">
+  <circle cx="65.454" cy="74.612" r="52.594" fill="none" stroke="#ced6d7" stroke-linecap="round" stroke-linejoin="round" stroke-width=".81951"/>
+  <circle cx="65.454" cy="74.612" r="44.738" fill="none" stroke="#ced6d7" stroke-linecap="round" stroke-linejoin="round" stroke-width=".81951"/>
+  <path d="m14.569 97.403c8.0095 17.537 24.454 29.831 43.54 32.551 4.3705 0.62286 11.576 0.62595 15.947 7e-3 19.106-2.7062 35.572-15.005 43.588-32.558 1.834-4.0156-0.78116-7.4867-5.1994-7.4867h-4.3699c-4.4183 0-9.475 3.3171-12.158 6.8168-5.4199 7.0691-13.19 11.996-21.895 13.883-4.3098 0.93438-11.569 0.93438-15.878 0-8.7055-1.8875-16.476-6.8143-21.895-13.883-2.6832-3.4997-7.7399-6.8168-12.158-6.8168h-4.3213c-4.4183 0-7.0335 3.4711-5.1994 7.4867z" fill="url(#linearGradient863)"/>
+  <g fill="#71a1c5">
+   <circle cx="24.82" cy="65.449" r="3.4954"/>
+   <circle cx="18.787" cy="80.168" r="5.4648"/>
+   <circle cx="104.11" cy="76.217" r="3.4954"/>
+   <circle cx="105.2" cy="49.262" r="3.4954"/>
+   <circle cx="27.911" cy="49.305" r="3.4954"/>
+   <circle cx="17.293" cy="56.258" r="3.0025"/>
+   <circle cx="114.94" cy="84.31" r="3.4954"/>
+  </g>
+  <g fill="#82accc">
+   <circle cx="55.866" cy="17.826" r="1.5789"/>
+   <circle cx="71.561" cy="12.748" r="1.5789"/>
+   <circle cx="44.99" cy="35.249" r="1.5789"/>
+   <circle cx="29.001" cy="32.979" r="1.5789"/>
+   <circle cx="71.755" cy="25.416" r="1.9259"/>
+   <circle cx="89.927" cy="28.528" r="1.9259"/>
+   <circle cx="93.483" cy="41.779" r="1.9259"/>
+   <circle cx="110.94" cy="58.799" r="1.9259"/>
+   <circle cx="113.08" cy="72.962" r="1.9259"/>
+  </g>
+  <g fill="#93b8d3">
+   <circle cx="43.007" cy="22.687" r=".79142"/>
+   <circle cx="62.554" cy="13.926" r=".79142"/>
+   <circle cx="67.844" cy="8.2041" r=".79142"/>
+   <circle cx="58.564" cy="2.7051" r=".79142"/>
+   <circle cx="58.816" cy="30.274" r=".79142"/>
+   <circle cx="104.8" cy="39.681" r=".79142"/>
+   <circle cx="105.28" cy="65.375" r=".79142"/>
+   <circle cx="109.7" cy="80.697" r=".79142"/>
+   <circle cx="25.323" cy="71.549" r=".79142"/>
+   <circle cx="15.745" cy="64.828" r=".79142"/>
+   <circle cx="82.057" cy="34.274" r=".79142"/>
+  </g>
+  <path transform="rotate(51.592)" d="m158.71-5.3528a59.249 59.249 0 0 1-43.914 57.23" fill="none" stroke="#3f7ca4" stroke-linecap="round" stroke-linejoin="round" stroke-width="2.7317"/>
+ </g>
+</svg>

documentation/source/class.rst

@@ -45,8 +45,6 @@ variable to set it in the ``conf.py``.
 The output includes references to any base classes and derived classes of the
 specified class.
 
-.. contents::
-
 
 Basic Example
 -------------

documentation/source/conf.py

@@ -29,7 +29,13 @@ import re
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ["breathe", "sphinx.ext.mathjax", "sphinx.ext.ifconfig", "sphinx.ext.graphviz"]
+extensions = [
+    "breathe",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.ifconfig",
+    "sphinx.ext.graphviz",
+    "sphinx_copybutton",
+]
 
 read_the_docs_build = os.environ.get("READTHEDOCS", None) == "True"
 travis_build = os.environ.get("TRAVIS_CI", None) == "True"
@@ -277,7 +283,7 @@ breathe_use_project_refids = True
 # given in html_static_path.
 # html_style = 'default.css'
 
-html_theme = "haiku"
+html_theme = "furo"
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
@@ -288,18 +294,19 @@ html_theme = "haiku"
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
-# html_logo = None
+html_logo = "_static/logo.svg"
 
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
 # pixels large.
-# html_favicon = None
+html_favicon = "_static/favicon.ico"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
 
+html_css_files = ["breathe.css"]
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
 # html_last_updated_fmt = '%b %d, %Y'

documentation/source/directives.rst

@@ -21,7 +21,6 @@ Directives & Config Variables
    autofile
    page
 
-.. contents:: Table of Contents
 
 Directives
 ----------

documentation/source/file.rst

@@ -62,7 +62,6 @@ The directive-specific options are documented below.
       "user-defined", "User defined"
       "var", "Variable"
 
-.. contents::
 
 Example
 -------

documentation/source/group.rst

@@ -54,7 +54,6 @@ variable to set it in the ``conf.py``.
 
 .. _doxygen grouping documentation: https://www.doxygen.nl/manual/grouping.html
 
-.. contents::
 
 
 Basic Example

documentation/source/namespace.rst

@@ -45,7 +45,6 @@ If you would like to always specify some combination of ``members``,
 use the :ref:`breathe_default_members <breathe-default-members>` configuration
 variable to set it in the ``conf.py``.
 
-.. contents::
 
 
 Basic Example

documentation/source/page.rst

@@ -19,7 +19,6 @@ It takes the standard ``project`` and ``path`` options.
 
 .. _doxygen documentation: https://www.doxygen.nl/manual/commands.html#cmdxrefitem
 
-.. contents::
 
 
 Basic Example

documentation/source/struct.rst

@@ -44,7 +44,6 @@ If you would like to always specify some combination of ``members``,
 use the :ref:`breathe_default_members <breathe-default-members>` configuration
 variable to set it in the ``conf.py``.
 
-.. contents::
 
 
 Basic Example

requirements/development.txt

@@ -9,3 +9,6 @@ types-docutils>=0.14,<0.18
 types-Pygments
 
 black==22.3.0
+
+sphinx-copybutton
+furo