[{"id":35732,"web_url":"https://patchwork.libcamera.org/comment/35732/","msgid":"<20250908224513.GC18349@pendragon.ideasonboard.com>","date":"2025-09-08T22:45:13","subject":"Re: [PATCH 3/6] Documentation: Use the sphinx book theme","submitter":{"id":2,"url":"https://patchwork.libcamera.org/api/people/2/","name":"Laurent Pinchart","email":"laurent.pinchart@ideasonboard.com"},"content":"Hi Stefan,\n\nThank you for the patch.\n\nOn Mon, Sep 08, 2025 at 04:07:46PM +0200, Stefan Klug wrote:\n> Our current theme doesn't handle many of the rst features (namely notes,\n> proper code highlighting, font formatting). The sphinx book theme theme\n\ns/theme theme/theme/\n\n> provides a unobtrusive design which makes the documentation way more fun\n\nI'm glad someone thinks it's fun to read the libcamera documentation :-)\n\n> to read. The branding is minimal. The libcamera logo is included and\n> theme colors are set to the libcamera blue.\n> \n> To get meson/sphinx to successfully compile the docs the package\n> \"python3-sphinx-book-theme\" needs to be installed (at least on debian\n> based systems).\n\nI'll update CI.\n\nsphinx-book-theme is annoyingly not packaged by Gentoo :-(\n\n> Signed-off-by: Stefan Klug \n> ---\n> Documentation/conf.py.in | 19 +-\n> Documentation/meson.build | 2 +-\n> Documentation/theme/footer.html | 14 -\n> Documentation/theme/layout.html | 109 -------\n> Documentation/theme/search.html | 63 ----\n> Documentation/theme/static/css/theme.css | 295 -------------------\n> Documentation/theme/static/custom.css | 5 +\n> Documentation/theme/static/logo-and-text.svg | 223 ++++++++++++++\n> Documentation/theme/static/search.png | Bin 482 -> 0 bytes\n> Documentation/theme/theme.conf | 7 -\n> README.rst | 4 +-\n> 11 files changed, 247 insertions(+), 494 deletions(-)\n> delete mode 100644 Documentation/theme/footer.html\n> delete mode 100644 Documentation/theme/layout.html\n> delete mode 100644 Documentation/theme/search.html\n> delete mode 100644 Documentation/theme/static/css/theme.css\n> create mode 100644 Documentation/theme/static/custom.css\n> create mode 100644 Documentation/theme/static/logo-and-text.svg\n> delete mode 100644 Documentation/theme/static/search.png\n> delete mode 100644 Documentation/theme/theme.conf\n> \n> diff --git a/Documentation/conf.py.in b/Documentation/conf.py.in\n> index 097e579b575b..44e9aaf133ef 100644\n> --- a/Documentation/conf.py.in\n> +++ b/Documentation/conf.py.in\n> @@ -88,8 +88,16 @@ doxylink = {\n> # The theme to use for HTML and HTML Help pages. See the documentation for\n> # a list of builtin themes.\n> #\n> -html_theme = 'theme'\n> -html_theme_path = ['@THEME_DIR@']\n> +html_theme = \"sphinx_book_theme\"\n> +html_theme_path = []\n> +\n> +html_logo = \"@CURRENT_SRCDIR@/theme/static/logo-and-text.svg\"\n> +\n> +html_context = {\n> + # Set the default mode, so that syntax highlighting works without\n> + # javascript.\n> + \"default_mode\": \"light\"\n> +}\n> \n> # Theme options are theme-specific and customize the look and feel of a theme\n> # further. For a list of options available for each theme, see the\n> @@ -100,7 +108,7 @@ html_theme_path = ['@THEME_DIR@']\n> # Add any paths that contain custom static files (such as style sheets) here,\n> # relative to this directory. They are copied after the builtin static files,\n> # so a file named \"default.css\" will overwrite the builtin \"default.css\".\n> -html_static_path = []\n> +html_static_path = ['@CURRENT_SRCDIR@/theme/static']\n> \n> # Custom sidebar templates, must be a dictionary that maps document names\n> # to template names.\n> @@ -111,3 +119,8 @@ html_static_path = []\n> # 'searchbox.html']``.\n> #\n> # html_sidebars = {}\n> +\n> +html_css_files = [\n> + 'custom.css',\n> +]\n> +\n> diff --git a/Documentation/meson.build b/Documentation/meson.build\n> index a8d4afc01dd1..f73407432fff 100644\n> --- a/Documentation/meson.build\n> +++ b/Documentation/meson.build\n> @@ -142,7 +142,7 @@ if sphinx.found()\n> sphinx_conf = configure_file(input : 'conf.py.in',\n> output : 'conf.py',\n> configuration : {\n> - 'THEME_DIR': meson.current_source_dir(),\n> + 'CURRENT_SRCDIR': meson.current_source_dir(),\n> 'TOP_BUILDDIR': meson.project_build_root(),\n> })\n> \n> diff --git a/Documentation/theme/footer.html b/Documentation/theme/footer.html\n> deleted file mode 100644\n> index 12939e8b7c12..000000000000\n> --- a/Documentation/theme/footer.html\n> +++ /dev/null\n\n[snip]\n\n> diff --git a/Documentation/theme/layout.html b/Documentation/theme/layout.html\n> deleted file mode 100644\n> index 4fffefab62eb..000000000000\n> --- a/Documentation/theme/layout.html\n> +++ /dev/null\n\n[snip]\n\n> diff --git a/Documentation/theme/search.html b/Documentation/theme/search.html\n> deleted file mode 100644\n> index 00c2af93a1b3..000000000000\n> --- a/Documentation/theme/search.html\n> +++ /dev/null\n\n[snip]\n\n> diff --git a/Documentation/theme/static/css/theme.css b/Documentation/theme/static/css/theme.css\n> deleted file mode 100644\n> index a6d43195c018..000000000000\n> --- a/Documentation/theme/static/css/theme.css\n> +++ /dev/null\n\n[snip]\n\n> diff --git a/Documentation/theme/static/custom.css b/Documentation/theme/static/custom.css\n> new file mode 100644\n> index 000000000000..c409f3670e1c\n> --- /dev/null\n> +++ b/Documentation/theme/static/custom.css\n> @@ -0,0 +1,5 @@\n\nPlease add an SPDX header.\n\n> +\n> +/* Hide the documentation nav. It is only used on the website. */\n> +.documentation-nav {\n> +\tdisplay: none;\n> +}\n> \\ No newline at end of file\n> diff --git a/Documentation/theme/static/logo-and-text.svg b/Documentation/theme/static/logo-and-text.svg\n> new file mode 100644\n> index 000000000000..4407f5d5ea89\n> --- /dev/null\n> +++ b/Documentation/theme/static/logo-and-text.svg\n\nFor SVG files, please add the license information to .reuse/dep5.\n\n[snip]\n\n> diff --git a/Documentation/theme/static/search.png b/Documentation/theme/static/search.png\n> deleted file mode 100644\n\nAnd remove the dep5 entry for search.png.\n\n> index a93c40eb08106554488deaed910aba0f5aef5ec5..0000000000000000000000000000000000000000\n> GIT binary patch\n> literal 0\n> HcmV?d00001\n> \n> literal 482\n> zcmV<80UiE{P) z000ie0hKEb8vpS{Qv(y11W$BjsN}6-{)Vx|M`d06c#vZ@BJ4Ihb|v`\n> z{Q4gQ11Af!uc~y5qrR#TFPa8Mh?6FtzL~%Ctf7Qpw2q<#567){pJ$)D^X1p?EfEg3\n> za$+bt{{R1f{K;#k=A~KNPW}D&?>`KD`0>kj!7kC>HSfRw{Eq|}{{R0UwEB?Fj4jBj\n> zA>iq!ZyasQJC9yP7Gz>zU^w*fRiw586C)# zoF9JtLf4=mz zWb|2a;MLb3aEbFT-iNL^%+1QID8PfP0U8e%UcUEQzW>wD-<~Q`l02L@-hA47{{;&Z\n> z)31O31UcCD$2#ka3!-RXU|{(0 z&Q(){4@Co3aOU|t=f!(I{rV%x!*M9iRYiywJ@KId6G@@%QBFLpEYH9E$l89Iunm|1\n> Y03N>L+`-G70ssI207*qoM6N<$g81y{PXGV_\n> \n> diff --git a/Documentation/theme/theme.conf b/Documentation/theme/theme.conf\n> deleted file mode 100644\n> index f2ab39c33c5b..000000000000\n> --- a/Documentation/theme/theme.conf\n> +++ /dev/null\n> @@ -1,7 +0,0 @@\n> -# SPDX-License-Identifier: CC-BY-SA-4.0\n> -\n> -[theme]\n> -inherit = basic\n> -stylesheet = css/theme.css\n> -\n> -[options]\n> diff --git a/README.rst b/README.rst\n> index 7c8bc6db6712..56b2e0956e36 100644\n> --- a/README.rst\n> +++ b/README.rst\n> @@ -67,8 +67,8 @@ for device hotplug enumeration: [optional]\n> libudev-dev\n> \n> for documentation: [optional]\n> - doxygen graphviz python3-sphinx python3-sphinxcontrib.doxylink (>= 1.6.1)\n> - texlive-latex-extra\n> + doxygen graphviz python3-sphinx python3-sphinx-book-theme\n> + python3-sphinxcontrib.doxylink (>= 1.6.1) texlive-latex-extra\n> \n> for gstreamer: [optional]\n> libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev","headers":{"Return-Path":"","X-Original-To":"parsemail@patchwork.libcamera.org","Delivered-To":"parsemail@patchwork.libcamera.org","Received":["from lancelot.ideasonboard.com (lancelot.ideasonboard.com\n\t[92.243.16.209])\n\tby patchwork.libcamera.org (Postfix) with ESMTPS id 23C2ABDB13\n\tfor ;\n\tMon, 8 Sep 2025 22:45:42 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id 93EE06935C;\n\tTue, 9 Sep 2025 00:45:40 +0200 (CEST)","from perceval.ideasonboard.com (perceval.ideasonboard.com\n\t[IPv6:2001:4b98:dc2:55:216:3eff:fef7:d647])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id A04616934F\n\tfor ;\n\tTue, 9 Sep 2025 00:45:37 +0200 (CEST)","from pendragon.ideasonboard.com (81-175-209-231.bb.dnainternet.fi\n\t[81.175.209.231])\n\tby perceval.ideasonboard.com (Postfix) with UTF8SMTPSA id A3891710;\n\tTue, 9 Sep 2025 00:44:24 +0200 (CEST)"],"Authentication-Results":"lancelot.ideasonboard.com; dkim=pass (1024-bit key;\n\tunprotected) header.d=ideasonboard.com header.i=@ideasonboard.com\n\theader.b=\"UQJNMiMt\"; dkim-atps=neutral","DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1757371464;\n\tbh=wJmWmcYCR9EqekTQb7PKh4WAtz0q33SyqpUhKVFYjkI=;\n\th=Date:From:To:Cc:Subject:References:In-Reply-To:From;\n\tb=UQJNMiMtKKhs63oIBZWXGsddNVJBmHuRTwxJpdg4vpHUIwih636ERwP10vwHRHzK6\n\t6PhtLg2nXl67QRp2eBaM9K1sSuzt+fdN4BVyEuuIqsv6FzWsniDJKG8PSQNqszfB4z\n\tYQXHx1boCPSglDkuRu2Jd5P5kHr3YNjDUm1gLWAs=","Date":"Tue, 9 Sep 2025 01:45:13 +0300","From":"Laurent Pinchart ","To":"Stefan Klug ","Cc":"libcamera-devel@lists.libcamera.org","Subject":"Re: [PATCH 3/6] Documentation: Use the sphinx book theme","Message-ID":"<20250908224513.GC18349@pendragon.ideasonboard.com>","References":"<20250908140803.123272-1-stefan.klug@ideasonboard.com>\n\t<20250908140803.123272-4-stefan.klug@ideasonboard.com>","MIME-Version":"1.0","Content-Type":"text/plain; charset=utf-8","Content-Disposition":"inline","In-Reply-To":"<20250908140803.123272-4-stefan.klug@ideasonboard.com>","X-BeenThere":"libcamera-devel@lists.libcamera.org","X-Mailman-Version":"2.1.29","Precedence":"list","List-Id":"","List-Unsubscribe":",\n\t","List-Archive":"","List-Post":"","List-Help":"","List-Subscribe":",\n\t","Errors-To":"libcamera-devel-bounces@lists.libcamera.org","Sender":"\"libcamera-devel\" "}}]