From patchwork Mon Sep 8 14:07:46 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Stefan Klug X-Patchwork-Id: 24293 Return-Path: X-Original-To: parsemail@patchwork.libcamera.org Delivered-To: parsemail@patchwork.libcamera.org Received: from lancelot.ideasonboard.com (lancelot.ideasonboard.com [92.243.16.209]) by patchwork.libcamera.org (Postfix) with ESMTPS id 6BE37BDB13 for ; Mon, 8 Sep 2025 14:08:39 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id 240916935C; Mon, 8 Sep 2025 16:08:39 +0200 (CEST) Authentication-Results: lancelot.ideasonboard.com; dkim=pass (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="oI4wYqBB"; dkim-atps=neutral Received: from perceval.ideasonboard.com (perceval.ideasonboard.com [IPv6:2001:4b98:dc2:55:216:3eff:fef7:d647]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id A338C69359 for ; Mon, 8 Sep 2025 16:08:36 +0200 (CEST) Received: from ideasonboard.com (unknown [IPv6:2a00:6020:448c:6c00:c241:40fd:9e5d:437c]) by perceval.ideasonboard.com (Postfix) with UTF8SMTPSA id 2B49D2F0D; Mon, 8 Sep 2025 16:07:24 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1757340444; bh=MPfs7IxIghnf9NV/MYtQSJ9kmjjDiNX62zZsty4pdZo=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=oI4wYqBBPS/cwn1PkNnniGqTw0qaga3MhQ/VgFGlKFI/nPAIuSU003FTmi095DLnL X9hGmrIOmylJW1L88uXhi3OviSQ8irmFarCIOimUIv2BntU4f16OKrZREZAVuOhBN+ xbgWmw8T8VD7ue9KRTDf69m1jDCj2r8DYNg242bE= From: Stefan Klug To: libcamera-devel@lists.libcamera.org Cc: Stefan Klug Subject: [PATCH 3/6] Documentation: Use the sphinx book theme Date: Mon, 8 Sep 2025 16:07:46 +0200 Message-ID: <20250908140803.123272-4-stefan.klug@ideasonboard.com> X-Mailer: git-send-email 2.48.1 In-Reply-To: <20250908140803.123272-1-stefan.klug@ideasonboard.com> References: <20250908140803.123272-1-stefan.klug@ideasonboard.com> MIME-Version: 1.0 X-BeenThere: libcamera-devel@lists.libcamera.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libcamera-devel-bounces@lists.libcamera.org Sender: "libcamera-devel" Our current theme doesn't handle many of the rst features (namely notes, proper code highlighting, font formatting). The sphinx book theme 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 --- 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 + Documentation/theme/static/logo-and-text.svg | 223 ++++++++++++++ Documentation/theme/static/search.png | Bin 482 -> 0 bytes Documentation/theme/theme.conf | 7 - README.rst | 4 +- 11 files changed, 247 insertions(+), 494 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/logo-and-text.svg delete mode 100644 Documentation/theme/static/search.png delete mode 100644 Documentation/theme/theme.conf diff --git a/Documentation/conf.py.in b/Documentation/conf.py.in index 097e579b575b..44e9aaf133ef 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/logo-and-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 a8d4afc01dd1..f73407432fff 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 12939e8b7c12..000000000000 --- 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 4fffefab62eb..000000000000 --- 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 00c2af93a1b3..000000000000 --- 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 a6d43195c018..000000000000 --- 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 000000000000..c409f3670e1c --- /dev/null +++ b/Documentation/theme/static/custom.css @@ -0,0 +1,5 @@ + +/* Hide the documentation nav. It is only used on the website. */ +.documentation-nav { + display: none; +} \ No newline at end of file diff --git a/Documentation/theme/static/logo-and-text.svg b/Documentation/theme/static/logo-and-text.svg new file mode 100644 index 000000000000..4407f5d5ea89 --- /dev/null +++ b/Documentation/theme/static/logo-and-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 f2ab39c33c5b..000000000000 --- 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 7c8bc6db6712..56b2e0956e36 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