From 8b8b01381d792adde034a2939e345d9b125d1a47 Mon Sep 17 00:00:00 2001 From: Stefan Klug Date: Mon, 8 Sep 2025 16:07:46 +0200 Subject: [PATCH] Documentation: Use the sphinx book theme Our current theme doesn't handle many of the rst features (namely notes, proper code highlighting, font formatting). The sphinx book theme provides a unobtrusive design which makes the documentation way more fun to read. The branding is minimal. The libcamera logo is included and theme colors are set to the libcamera blue. To get meson/sphinx to successfully compile the docs the package "python3-sphinx-book-theme" needs to be installed (at least on debian based systems). Signed-off-by: Stefan Klug Signed-off-by: Laurent Pinchart Reviewed-by: Stefan Klug --- .reuse/dep5 | 5 +- Documentation/conf.py.in | 19 +- Documentation/meson.build | 2 +- Documentation/theme/footer.html | 14 - Documentation/theme/layout.html | 109 ------- Documentation/theme/search.html | 63 ---- Documentation/theme/static/css/theme.css | 295 ------------------ Documentation/theme/static/custom.css | 5 + .../theme/static/libcamera-logo-text.svg | 223 +++++++++++++ Documentation/theme/static/search.png | Bin 482 -> 0 bytes Documentation/theme/theme.conf | 7 - README.rst | 4 +- 12 files changed, 248 insertions(+), 498 deletions(-) delete mode 100644 Documentation/theme/footer.html delete mode 100644 Documentation/theme/layout.html delete mode 100644 Documentation/theme/search.html delete mode 100644 Documentation/theme/static/css/theme.css create mode 100644 Documentation/theme/static/custom.css create mode 100644 Documentation/theme/static/libcamera-logo-text.svg delete mode 100644 Documentation/theme/static/search.png delete mode 100644 Documentation/theme/theme.conf diff --git a/.reuse/dep5 b/.reuse/dep5 index c5ef5e01..9cdb56e8 100644 --- a/.reuse/dep5 +++ b/.reuse/dep5 @@ -6,13 +6,10 @@ Source: https://git.libcamera.org/libcamera/libcamera.git/ Files: Documentation/binning.svg Documentation/camera-sensor-model.rst Documentation/sensor_model.svg + Documentation/theme/static/libcamera-logo-text.svg Copyright: Copyright 2023 Ideas On Board Oy License: CC-BY-SA-4.0 -Files: Documentation/theme/static/search.png -Copyright: 2022 Fonticons, Inc. -License: CC-BY-4.0 - Files: src/ipa/rpi/vc4/data/*.json utils/raspberrypi/ctt/ctt_config_example.json utils/raspberrypi/ctt/ctt_ref.pgm diff --git a/Documentation/conf.py.in b/Documentation/conf.py.in index 097e579b..34fa3956 100644 --- a/Documentation/conf.py.in +++ b/Documentation/conf.py.in @@ -88,8 +88,16 @@ doxylink = { # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = 'theme' -html_theme_path = ['@THEME_DIR@'] +html_theme = 'sphinx_book_theme' +html_theme_path = [] + +html_logo = '@CURRENT_SRCDIR@/theme/static/libcamera-logo-text.svg' + +html_context = { + # Set the default mode, so that syntax highlighting works without + # javascript. + 'default_mode': 'light' +} # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the @@ -100,7 +108,7 @@ html_theme_path = ['@THEME_DIR@'] # 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 = [] +html_static_path = ['@CURRENT_SRCDIR@/theme/static'] # Custom sidebar templates, must be a dictionary that maps document names # to template names. @@ -111,3 +119,8 @@ html_static_path = [] # 'searchbox.html']``. # # html_sidebars = {} + +html_css_files = [ + 'custom.css', +] + diff --git a/Documentation/meson.build b/Documentation/meson.build index a8d4afc0..f7340743 100644 --- a/Documentation/meson.build +++ b/Documentation/meson.build @@ -142,7 +142,7 @@ if sphinx.found() sphinx_conf = configure_file(input : 'conf.py.in', output : 'conf.py', configuration : { - 'THEME_DIR': meson.current_source_dir(), + 'CURRENT_SRCDIR': meson.current_source_dir(), 'TOP_BUILDDIR': meson.project_build_root(), }) diff --git a/Documentation/theme/footer.html b/Documentation/theme/footer.html deleted file mode 100644 index 12939e8b..00000000 --- a/Documentation/theme/footer.html +++ /dev/null @@ -1,14 +0,0 @@ -{# -SPDX-License-Identifier: CC-BY-SA-4.0 -#} -
-
- {%- if show_copyright %} - {%- if hasdoc('copyright') %} - {% trans path=pathto('copyright'), copyright=copyright|e %}© Copyright {{ copyright }}.{% endtrans %} - {%- else %} - {% trans copyright=copyright|e %}© Copyright {{ copyright }}.{% endtrans %} - {%- endif %} - {%- endif %} -
-
diff --git a/Documentation/theme/layout.html b/Documentation/theme/layout.html deleted file mode 100644 index 4fffefab..00000000 --- a/Documentation/theme/layout.html +++ /dev/null @@ -1,109 +0,0 @@ -{# -SPDX-License-Identifier: CC-BY-SA-4.0 -#} -{# TEMPLATE VAR SETTINGS #} -{%- set url_root = pathto('', 1) %} -{%- if url_root == '#' %}{% set url_root = '' %}{% endif %} -{%- if not embedded and docstitle %} - {%- set titlesuffix = " — "|safe + docstitle|e %} -{%- else %} - {%- set titlesuffix = "" %} -{%- endif %} - - - - {{ metatags }} - - {% block htmltitle %} - {{ title|striptags|e }}{{ titlesuffix }} - {% endblock %} - - {# FAVICON #} - {% if favicon %} - - {% endif %} - - {# CSS #} - - {# OPENSEARCH #} - {% if not embedded %} - {% if use_opensearch %} - - {% endif %} - - {% endif %} - - {% for cssfile in css_files %} - - {% endfor %} - - {% for cssfile in extra_css_files %} - - {% endfor %} - - {%- block linktags %} - {%- if hasdoc('about') %} - - {%- endif %} - {%- if hasdoc('genindex') %} - - {%- endif %} - {%- if hasdoc('search') %} - - {%- endif %} - {%- if hasdoc('copyright') %} - - {%- endif %} - - {%- if parents %} - - {%- endif %} - {%- if next %} - - {%- endif %} - {%- if prev %} - - {%- endif %} - {%- endblock %} - {%- block extrahead %} {% endblock %} - - - - -
- -
- -
- {# PAGE CONTENT #} -
- {% block body %}{% endblock %} -
-
- - {% include "footer.html" %} - - diff --git a/Documentation/theme/search.html b/Documentation/theme/search.html deleted file mode 100644 index 00c2af93..00000000 --- a/Documentation/theme/search.html +++ /dev/null @@ -1,63 +0,0 @@ -{# -SPDX-License-Identifier: CC-BY-SA-4.0 -#} -{# - basic/search.html - ~~~~~~~~~~~~~~~~~ - - Template for the search page. - - :copyright: Copyright 2007-2018 by the Sphinx team, see AUTHORS. - :license: BSD, see LICENSE for details. -#} -{%- extends "layout.html" %} -{% block extrahead %} - - {%- for scriptfile in script_files %} - - {%- endfor %} - - - {# this is used when loading the search index using $.ajax fails, - such as on Chrome for documents on localhost #} - -{% endblock %} -{% block body %} -

{{ _('Search') }}

-
- -

- Please activate JavaScript to enable the search functionality. -

-
-

- From here you can search these documents. Enter your search - words into the box below and click "search". Note that the search - function will automatically search for all of the words. Pages - containing fewer words won't appear in the result list. -

-
- - - -
- {% if search_performed %} -

{{ _('Search Results') }}

- {% if not search_results %} -

{{ _('Your search did not match any documents. Please make sure that all words are spelled correctly and that you\'ve selected enough categories.') }}

- {% endif %} - {% endif %} -
- {% if search_results %} -
    - {% for href, caption, context in search_results %} -
  • {{ caption }} -
    {{ context|e }}
    -
    • - {% endfor %} -
- {% endif %} -
-{% endblock %} diff --git a/Documentation/theme/static/css/theme.css b/Documentation/theme/static/css/theme.css deleted file mode 100644 index a6d43195..00000000 --- a/Documentation/theme/static/css/theme.css +++ /dev/null @@ -1,295 +0,0 @@ -/* SPDX-License-Identifier: CC-BY-SA-4.0 */ - -html { - background-image: linear-gradient(to bottom right, #4895e1, #56c3ae); - background-size: cover; - background-repeat: no-repeat; - min-height: 100vh; -} - -body { - color: rgb(0, 0, 0, 0.65); - font-family: Arial, sans-serif; - margin: 0px; -} - -a { - color: unset; - font-weight: bold; - text-decoration: underline dotted; -} - -a.headerlink { - color: rgba(0, 0, 0, 0.2); - font-size: 70%; - padding-left: 5px; - visibility: hidden; -} - -a.toc-backref { - text-decoration: none; -} - -h1:hover a.headerlink, -h2:hover a.headerlink, -h3:hover a.headerlink, -h4:hover a.headerlink, -h5:hover a.headerlink, -h6:hover a.headerlink { - visibility: visible; -} - -dt { - font-weight: bold; -} - -.text-light { - color: rgba(255, 255, 255, 0.3); -} - -div#navbar { - margin-top: 0px; -} - -div.navbar-brand { - color: rgb(255, 255, 255, 1.0); - float: left; - font-size: 36px; - margin: 0px 24px 24px 24px; -} - -div.navbar-logo { - float: left; - font-family: monospace; - font-size: 18px; - font-weight: bold; - white-space: pre; -} - -div.navbar-name { - float: left; - color: rgb(255, 255, 255, 1.0); - font-size: 34px; - margin-top: 31px; - margin-left: 10px; - padding-top: 1px; -} - -div.navbar { - float: right; -} - -div.navbar p.caption { - height: 0px; - margin: 0px; - visibility: hidden; -} - -div.navbar ul { - float: left; - font-size: 24px; - list-style: none; - margin-top: 42px; - margin-right: 20px; - padding-left: 0px; -} - -div.navbar a { - font-weight: normal; - text-decoration: none; -} - -div.navbar li { - float: left; - margin-left: 20px; - margin-right: 20px; - position: relative; -} - -div.navbar li a { - color: rgb(255, 255, 255, 0.5); - position: relative; -} - -div.navbar li a:before { - content: ""; - position: absolute; - width: 100%; - height: 2px; - bottom: 0; - left: 0; - background-color: rgb(255, 255, 255, 0.5); - visibility: hidden; - transform: scaleX(0); - transition: all 0.3s ease-in-out 0s; -} - -div.navbar li a:hover { - color: rgb(255, 255, 255, 1.0); -} - -div.navbar li a:hover:before { - visibility: visible; - transform: scaleX(1); -} - -div.navbar li.current a { - color: rgb(255, 255, 255, 1.0); -} - -div.navbar li.current a:before { - visibility: visible; - transform: unset; - transition: unset; -} - -div.navbar div.searchbox { - background-color: white; - float: right; - margin-right: 50px; - margin-top: 42px; -} - -div.navbar input[type=text] { - border-width: 0; - height: 2em; - margin-left: 10px; - margin-right: 5px; -} - -div.navbar input[type=submit] { - background-color: white; - background-image: url(../search.png); - background-repeat: no-repeat; - border-width: 0; - color: rgba(0, 0, 0, 0); - margin-right: 2px; - width: 20px; -} - -div#frontpage { - clear: both; - padding-top: 50px; - margin-left: auto; - margin-right: auto; - width: 75%; - display: flex; - justify-content: space-between; -} - -div#frontpage > div.block { - background-color: white; - border-radius: 5px; - box-shadow: 0 4px 16px 0 rgba(0, 0, 0, 0.2), 0 6px 40px 0 rgba(0, 0, 0, 0.19); - color: rgb(0, 0, 0, 0.5); - font-size: 20px; - margin-bottom: 40px; - margin-right: 20px; - margin-left: 20px; - padding: 20px 60px 20px 60px; - text-align: center; - width: 50%; -} - -div#frontpage > div.block h1 { - font-size: 64px; - padding-left: 20%; - padding-right: 20%; - text-align: center; - text-shadow: 4px 4px 5px; -} - -div#content { - background-color: white; - clear: both; - padding-top: 50px; - padding-bottom: 50px; - margin-left: 0px; - margin-right: 0px; -} - -div#content > div.block { - font-size: 16px; - margin-right: 0px; - margin-left: 0px; - max-width: 1280px; - padding: 0px 60px 0px 60px; - text-align: justify; -} - -div#content > div.block h1 { - font-size: 40px; - margin-top: 0px; - text-align: left; -} - -div#content > div.block > div.section { - max-width: 800px; -} - -div.local.topic { - float: right; - background-color: #fcfcff; - border: 1px dotted #4896e0; - margin-left: 20px; - margin-right: 0px; - max-width: 15em; - padding: 10px 20px 10px 10px; - text-align: left; -} - -div.local.topic ul { - padding-left: 20px; - margin-bottom: 5px; -} - -div.local.topic > ul:before { - content: "Contents"; - display: block; - font-weight: bold; - margin-bottom: 10px; -} - -div.local.topic a { - font-weight: normal; - padding-left: 10px; - text-decoration: none; -} - -div.highlight-shell > div.highlight > pre, -pre.console { - background-color: #fcfcff; - border: 1px dotted #4896e0; - margin-left: 0em; - padding: 10px; - text-align: left; -} - -div.highlight-default > div.highlight > pre, -pre.diagram { - background-color: #fcfcff; - border: 1px dotted #4896e0; - font-size: 12px; - margin-left: 0em; - padding: 10px; - text-align: left; - width: 47em; -} - -div#signature { - color: rgb(255, 255, 255, 0.5); - margin: 20px; - float: right; - font-size: 12px; -} - -#licensing div.toctree-wrapper { - height: 0px; - margin: 0px; - padding: 0px; - visibility: hidden; -} - -.documentation-nav { - display: none; -} diff --git a/Documentation/theme/static/custom.css b/Documentation/theme/static/custom.css new file mode 100644 index 00000000..0be62294 --- /dev/null +++ b/Documentation/theme/static/custom.css @@ -0,0 +1,5 @@ +/* SPDX-License-Identifier: CC-BY-SA-4.0 */ +/* Hide the documentation nav. It is only used on the website. */ +.documentation-nav { + display: none; +} diff --git a/Documentation/theme/static/libcamera-logo-text.svg b/Documentation/theme/static/libcamera-logo-text.svg new file mode 100644 index 00000000..e623e321 --- /dev/null +++ b/Documentation/theme/static/libcamera-logo-text.svg @@ -0,0 +1,223 @@ + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/Documentation/theme/static/search.png b/Documentation/theme/static/search.png deleted file mode 100644 index a93c40eb08106554488deaed910aba0f5aef5ec5..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 482 zcmV<80UiE{P)S{Qv(y11W$BjsN}6-{)Vx|M`d06c#vZ@BJ4Ihb|v` z{Q4gQ11Af!uc~y5qrR#TFPa8Mh?6FtzL~%Ctf7Qpw2q<#567){pJ$)D^X1p?EfEg3 za$+bt{{R1f{K;#k=A~KNPW}D&?>`KD`0>kj!7kC>HSfRw{Eq|}{{R0UwEB?Fj4jBj zA>iq!ZyasQJC9yP7Gz>zU^w*fRiw586C)#wD-<~Q`l02L@-hA47{{;&Z z)31O31UcCD$2#ka3!-RXU|{(0L+`-G70ssI207*qoM6N<$g81y{PXGV_ diff --git a/Documentation/theme/theme.conf b/Documentation/theme/theme.conf deleted file mode 100644 index f2ab39c3..00000000 --- a/Documentation/theme/theme.conf +++ /dev/null @@ -1,7 +0,0 @@ -# SPDX-License-Identifier: CC-BY-SA-4.0 - -[theme] -inherit = basic -stylesheet = css/theme.css - -[options] diff --git a/README.rst b/README.rst index 7c8bc6db..56b2e095 100644 --- a/README.rst +++ b/README.rst @@ -67,8 +67,8 @@ for device hotplug enumeration: [optional] libudev-dev for documentation: [optional] - doxygen graphviz python3-sphinx python3-sphinxcontrib.doxylink (>= 1.6.1) - texlive-latex-extra + doxygen graphviz python3-sphinx python3-sphinx-book-theme + python3-sphinxcontrib.doxylink (>= 1.6.1) texlive-latex-extra for gstreamer: [optional] libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev