From patchwork Wed Aug 14 08:41:02 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Stefan Klug X-Patchwork-Id: 20908 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 004BCBDB13 for ; Wed, 14 Aug 2024 08:42:27 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id A549661946; Wed, 14 Aug 2024 10:42:27 +0200 (CEST) Authentication-Results: lancelot.ideasonboard.com; dkim=pass (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="Hdy2QwTU"; 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 899B963398 for ; Wed, 14 Aug 2024 10:42:25 +0200 (CEST) Received: from ideasonboard.com (unknown [IPv6:2a00:6020:448c:6c00:8a6:aa2:ebee:5ae5]) by perceval.ideasonboard.com (Postfix) with ESMTPSA id 94A012E0; Wed, 14 Aug 2024 10:41:27 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1723624887; bh=uurSNzV9rdfxl6M4eBeLx20T7PytnIBGroKg6Yx3mu0=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Hdy2QwTUuocigfMtMsPfdt36akOqs4dd88X/0UjKHCPxl4GIlxGJSHL5TITnJFII6 8qB9vJH+SU7BVMaQ1Dg/frowg9ZFxg6kc4G103rbF2NI8Cf+LJAD3aFOzHNtHG3fVR 22b6tXqGryCZhPCDrX0sDrjfA/gXXgnbgi70L2c8= From: Stefan Klug To: libcamera-devel@lists.libcamera.org Cc: Stefan Klug Subject: [PATCH v1 1/2] Documentation: Use the furo sphinx theme Date: Wed, 14 Aug 2024 10:41:02 +0200 Message-ID: <20240814084215.61857-2-stefan.klug@ideasonboard.com> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20240814084215.61857-1-stefan.klug@ideasonboard.com> References: <20240814084215.61857-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 furo 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 "furo" needs to be installed (at least on debian based systems). Signed-off-by: Stefan Klug --- Documentation/conf.py | 17 +- Documentation/theme/footer.html | 14 - Documentation/theme/layout.html | 109 ------- Documentation/theme/search.html | 63 ---- Documentation/theme/static/css/theme.css | 291 ------------------- Documentation/theme/static/logo-and-text.svg | 223 ++++++++++++++ Documentation/theme/static/search.png | Bin 482 -> 0 bytes Documentation/theme/theme.conf | 7 - README.rst | 2 +- 9 files changed, 238 insertions(+), 488 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/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 b/Documentation/conf.py index 7eeea7f3865b..022e698efac4 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -72,8 +72,19 @@ pygments_style = None # 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 = ['.'] +html_theme = "furo" + +html_logo = "theme/static/logo-and-text.svg" + +html_theme_options = { + "light_css_variables": { + "color-brand-primary": "#4a9bd9", + "color-brand-content": "#4a9bd9F", + }, + "sidebar_hide_name": True, +} + +# html_theme_path = ['.'] # 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 @@ -84,7 +95,7 @@ html_theme_path = ['.'] # 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 = [] # Custom sidebar templates, must be a dictionary that maps document names # to template names. 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 d4274ea6f65d..000000000000 --- a/Documentation/theme/static/css/theme.css +++ /dev/null @@ -1,291 +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; -} - -#libcamera div.toctree-wrapper { - height: 0px; - margin: 0px; - padding: 0px; - visibility: hidden; -} 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 92f165022988..2fc98d2eaf15 100644 --- a/README.rst +++ b/README.rst @@ -70,7 +70,7 @@ for device hotplug enumeration: [optional] libudev-dev for documentation: [optional] - python3-sphinx doxygen graphviz texlive-latex-extra + python3-sphinx furo doxygen graphviz texlive-latex-extra for gstreamer: [optional] libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev From patchwork Wed Aug 14 08:41:03 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Stefan Klug X-Patchwork-Id: 20909 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 53345BDB13 for ; Wed, 14 Aug 2024 08:42:33 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id E6C5D633C0; Wed, 14 Aug 2024 10:42:32 +0200 (CEST) Authentication-Results: lancelot.ideasonboard.com; dkim=pass (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="bzQ243th"; dkim-atps=neutral Received: from perceval.ideasonboard.com (perceval.ideasonboard.com [213.167.242.64]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id 750E6633BF for ; Wed, 14 Aug 2024 10:42:28 +0200 (CEST) Received: from ideasonboard.com (unknown [IPv6:2a00:6020:448c:6c00:8a6:aa2:ebee:5ae5]) by perceval.ideasonboard.com (Postfix) with ESMTPSA id BBE059FF; Wed, 14 Aug 2024 10:41:30 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1723624890; bh=buW6W8OInYbXhZvVAy41lNfViDRXc0wjfgd3HqbKD58=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=bzQ243tholqvJEgekLHPHGZZEM0VYj538zrOAa5i4QOvvpZm1fJRUvmAro9XKq2Pi pc9SOpduQ96jwkvV8zReX6hwpHFl4XC1hmQt81S7dBvO7EPt118QScg+iVov0eWUSp mZYPIzy1LsvP2lSeBDiO1GlqHJM6R2+sGEZZ0eUw= From: Stefan Klug To: libcamera-devel@lists.libcamera.org Cc: Stefan Klug Subject: [PATCH v1 2/2] Documentation: Add tuning guide from external source Date: Wed, 14 Aug 2024 10:41:03 +0200 Message-ID: <20240814084215.61857-3-stefan.klug@ideasonboard.com> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20240814084215.61857-1-stefan.klug@ideasonboard.com> References: <20240814084215.61857-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" Add the external tuning guide as meson subproject. Symlink it into the Documentation/guides directory, so that sphinx can pick it up. This setup feels a bit cumbersome, therefore I try to explain the reasoning (and maybe someone comes up with a better solution): The main reason is that we don't want to have large binary files (aka images) in the main libcamera repository. Especially if they change a lot the repository size increases tremendously. In a meson based project, meson subprojects are the way to go. This however has the following side effects: - The subprojects needs to contain a meson.build (That's why libcamera-tuning-guide is also meson based) - We can't reference ../subproject/libcamera-tuning-guide/tuning.rst from within the main meson build, as that violates the meson sandbox - Referencing ../subproject/libcamera-tuning-guide/tuning.rst via a sphinx include directive doesn't work either as sphinx then tries to resolve images relative to the outer document. - Symlinking ../subprojects/libcameta-tuning-guide into Documentation/guides works wuite well, but fails as soon as libcamera-tuning-guide contains an additional rst file (like index.rst) which is not referenced from the libcamera documentation. The solution is to move the actual content into ../subproject/libcamera-tuning-guide/content/ and to symlink that directory into Documentation/guides. Signed-off-by: Stefan Klug --- Documentation/conf.py | 4 ++-- Documentation/guides/tuning | 1 + Documentation/index.rst | 1 + Documentation/meson.build | 2 ++ subprojects/libcamera-tuning-guide.wrap | 7 +++++++ 5 files changed, 13 insertions(+), 2 deletions(-) create mode 120000 Documentation/guides/tuning create mode 100644 subprojects/libcamera-tuning-guide.wrap diff --git a/Documentation/conf.py b/Documentation/conf.py index 022e698efac4..7675efb6682a 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -21,8 +21,8 @@ # -- Project information ----------------------------------------------------- project = 'libcamera' -copyright = '2018-2019, The libcamera documentation authors' -author = u'Kieran Bingham, Jacopo Mondi, Laurent Pinchart, Niklas Söderlund' +copyright = '2018-2024, The libcamera documentation authors' +author = u'Kieran Bingham, Jacopo Mondi, Laurent Pinchart, Niklas Söderlund, Stefan Klug' # Version information is provided by the build environment, through the # sphinx command line. diff --git a/Documentation/guides/tuning b/Documentation/guides/tuning new file mode 120000 index 000000000000..3e62b7b660d0 --- /dev/null +++ b/Documentation/guides/tuning @@ -0,0 +1 @@ +../../subprojects/libcamera-tuning-guide/content/ \ No newline at end of file diff --git a/Documentation/index.rst b/Documentation/index.rst index 5442ae75dde7..991dcf2b66fb 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -16,6 +16,7 @@ Developer Guide Application Writer's Guide + Sensor Tuning Guide Pipeline Handler Writer's Guide IPA Writer's guide Tracing guide diff --git a/Documentation/meson.build b/Documentation/meson.build index 1ba40fdf67ac..58c656a54150 100644 --- a/Documentation/meson.build +++ b/Documentation/meson.build @@ -143,6 +143,8 @@ if sphinx.found() '../README.rst', ] + subproject('libcamera-tuning-guide', required : true) + release = 'release=v' + libcamera_git_version custom_target('documentation', diff --git a/subprojects/libcamera-tuning-guide.wrap b/subprojects/libcamera-tuning-guide.wrap new file mode 100644 index 000000000000..d8e172471fa6 --- /dev/null +++ b/subprojects/libcamera-tuning-guide.wrap @@ -0,0 +1,7 @@ +# SPDX-License-Identifier: CC0-1.0 + +[wrap-git] +directory = libcamera-tuning-guide +url = https://git.uk.ideasonboard.com/sklug/libcamera-tuning-guide.git +# tags/0.2.5 +revision = head