Browse Source

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
pull/820/head
2bndy5 6 months ago committed by Melvin Vermeeren
parent
commit
719a363ad0
No known key found for this signature in database
GPG Key ID: A72F627716EA9D96
  1. 103
      documentation/source/_static/breathe.css
  2. BIN
      documentation/source/_static/favicon.ico
  3. 49
      documentation/source/_static/logo.svg
  4. 2
      documentation/source/class.rst
  5. 15
      documentation/source/conf.py
  6. 1
      documentation/source/directives.rst
  7. 1
      documentation/source/file.rst
  8. 1
      documentation/source/group.rst
  9. 1
      documentation/source/namespace.rst
  10. 1
      documentation/source/page.rst
  11. 1
      documentation/source/struct.rst
  12. 3
      requirements/development.txt

103
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;
}

BIN
documentation/source/_static/favicon.ico

Binary file not shown.

After

Width:  |  Height:  |  Size: 4.2 KiB

49
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>

After

Width:  |  Height:  |  Size: 2.8 KiB

2
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
-------------

15
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'

1
documentation/source/directives.rst

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

1
documentation/source/file.rst

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

1
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

1
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

1
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

1
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

3
requirements/development.txt

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