From patchwork Thu Oct 13 17:29:13 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jonathan Corbet X-Patchwork-Id: 2110 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a5d:4ac7:0:0:0:0:0 with SMTP id y7csp397020wrs; Thu, 13 Oct 2022 10:36:24 -0700 (PDT) X-Google-Smtp-Source: AMsMyM6F1PrSBfnNjExMq+zclWC83+a+JFWNkwW/rqUoHv5+0hQSNA9AoZt0eiPqITT/aKplBdzY X-Received: by 2002:a17:907:3d91:b0:78d:f675:5659 with SMTP id he17-20020a1709073d9100b0078df6755659mr660331ejc.92.1665682584352; Thu, 13 Oct 2022 10:36:24 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1665682584; cv=none; d=google.com; s=arc-20160816; b=I5MS7MU6DI3P8gYcRUrzO+Osmtyu6jx7wJU0a4XOK9ycxPGXtImN6r1NaA9JWaeDS3 wnXaB7bOQ1Q8QoaCRlCHK5IUnWBFamXmEE0w4g4IH6LlxsThviDP06885UeSapMGEzcj l3uPiVByP18BeX/onGm6PxCxogZxZB/Gu9cmxnNLGOow0i7hels4P+l039ij9r9eFdIB a+zS0pWnY9bROShr9kFlmFGjWzbA9Qj88caqQ/JuxAJ+4qtyhUwOSREXmrPhvOee0t/u ULYax/PqkCIout7Bvk/HX9073caP+z934AyejsN9MOH8C4raBAOA7CNq8SJcOhEy/Cdf 9NRA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:content-transfer-encoding:mime-version :references:in-reply-to:message-id:date:subject:cc:to:from :dkim-signature:dkim-filter; bh=GPZZbukyBGUR5a86BzVdFY5tNFwcRKGUe05DCy1zk04=; b=wgxayZszMNvNWCjS3AAk8cSQpJ8h2xXwNZDp8RZgzu5SnA5H/dA8k568OuIGobe2Yv MjbbAm6jpQ7jQblgVTqfgKIOb9Zf0DnxaUS8nMFAUXl5jO+Itvu8x67UT5GqtOkKHNhN yTAu9MZOfrVpQJn+GJExaC1m0SOsfqaI2DA2L81U2enzaX9r4TieGigagfPuD8yBW/Kl qrpachifGIvEeUOiOgNLb/vWIR+MpTsKKrU7OBEbFvl3tkFSNuWXGSwRWNveRN2um6qB s2KaIMmV7O9OHvne++4fcTyopFo+3kEnNUO79X0mcAHRvnzQvLKusxyGU6uXaV222WsK GCFA== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@lwn.net header.s=20201203 header.b=iGsJwX2B; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: from out1.vger.email (out1.vger.email. [2620:137:e000::1:20]) by mx.google.com with ESMTP id x18-20020a1709060ef200b0077a6429787dsi267246eji.157.2022.10.13.10.35.58; Thu, 13 Oct 2022 10:36:24 -0700 (PDT) Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20; Authentication-Results: mx.google.com; dkim=pass header.i=@lwn.net header.s=20201203 header.b=iGsJwX2B; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229867AbiJMR3b (ORCPT + 99 others); Thu, 13 Oct 2022 13:29:31 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:48178 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229470AbiJMR31 (ORCPT ); Thu, 13 Oct 2022 13:29:27 -0400 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id D7292C34E3; Thu, 13 Oct 2022 10:29:26 -0700 (PDT) Received: from meer.lwn.net (unknown [IPv6:2601:281:8300:73:8b7:7001:c8aa:b65f]) by ms.lwn.net (Postfix) with ESMTPA id 78173845; Thu, 13 Oct 2022 17:29:26 +0000 (UTC) DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 78173845 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1665682166; bh=GPZZbukyBGUR5a86BzVdFY5tNFwcRKGUe05DCy1zk04=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=iGsJwX2B2cftuZzw4pvOPmwBZ3A6w9DXtitUXVKpb9s/Qfj0kXgL8JzdDaGQ3iD2u W/KhRS6FQzv2ff2tkeZoYhT1MsLOJVEUYv/h3zChui0WEe1felJ7R4o+FMde4vDurV XLdNCZLqfC6v9MUg1YkXF/vHnQOE58AmsBK+wR9adKPjHcZ6D6CV3Cgn1BviuOeOaG gxrbqpD3aWinED2Edjp+xW/UipN+Gmd78L0gh9erHbaPlgxi91xRwahxXbmU0EOSu6 q1R2ita4AvqnubQmmUnb+eFSBEbZK3dISPacuFbI+GLkItM1xDFvgcvSvQOVQjAisQ caDFkNchGG60g== From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org Subject: [PATCH v3 1/6] docs: Switch the default HTML theme to alabaster Date: Thu, 13 Oct 2022 11:29:13 -0600 Message-Id: <20221013172918.846856-2-corbet@lwn.net> X-Mailer: git-send-email 2.37.2 In-Reply-To: <20221013172918.846856-1-corbet@lwn.net> References: <20221013172918.846856-1-corbet@lwn.net> MIME-Version: 1.0 X-Spam-Status: No, score=-2.1 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,RCVD_IN_DNSWL_NONE, SPF_HELO_NONE,SPF_PASS autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on lindbergh.monkeyblade.net Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org X-getmail-retrieved-from-mailbox: =?utf-8?q?INBOX?= X-GMAIL-THRID: =?utf-8?q?1746594781529136098?= X-GMAIL-MSGID: =?utf-8?q?1746594781529136098?= The read-the-docs theme is not entirely attractive and doesn't give us control over the left column. "Alabaster" is deemed the default Sphinx theme, it is currently maintained and shipped bundled with Sphinx itself, so there is no need to install it separately. Switch over to this theme as the default for building kernel documentation; the DOCS_THEME environment variable can still be used to select a different theme. Acked-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/conf.py | 28 +++++++++++++++++++++++++--- 1 file changed, 25 insertions(+), 3 deletions(-) diff --git a/Documentation/conf.py b/Documentation/conf.py index b50c85083149..629f4afeb0eb 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -194,6 +194,24 @@ finally: else: version = release = "unknown version" +# +# HACK: there seems to be no easy way for us to get at the version and +# release information passed in from the makefile...so go pawing through the +# command-line options and find it for ourselves. +# +def get_cline_version(): + c_version = c_release = '' + for arg in sys.argv: + if arg.startswith('version='): + c_version = arg[8:] + elif arg.startswith('release='): + c_release = arg[8:] + if c_version: + if c_release: + return c_version + '-' + c_release + return c_version + return version # Whatever we came up with before + # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. # @@ -247,7 +265,7 @@ highlight_language = 'none' # a list of builtin themes. # Default theme -html_theme = 'sphinx_rtd_theme' +html_theme = 'alabaster' html_css_files = [] if "DOCS_THEME" in os.environ: @@ -324,6 +342,10 @@ if html_theme == 'classic': 'bodyfont': "serif", 'headfont': "sans-serif", } +else: + html_theme_options = { + 'description': get_cline_version(), + } sys.stderr.write("Using %s theme\n" % html_theme) @@ -370,8 +392,8 @@ html_static_path = ['sphinx-static'] html_use_smartypants = False # Custom sidebar templates, maps document names to template names. -# Note that the RTD theme ignores this. -html_sidebars = { '**': ['searchbox.html', 'localtoc.html', 'sourcelink.html']} +# Note that the RTD theme ignores this +html_sidebars = { '**': ["about.html", 'searchbox.html', 'localtoc.html', 'sourcelink.html']} # Additional templates that should be rendered to pages, maps page names to # template names. From patchwork Thu Oct 13 17:29:14 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jonathan Corbet X-Patchwork-Id: 2105 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a5d:4ac7:0:0:0:0:0 with SMTP id y7csp396158wrs; Thu, 13 Oct 2022 10:34:24 -0700 (PDT) X-Google-Smtp-Source: AMsMyM7pvqdomovViQy9Kq4Eo7MnGPaUAyy38Htc3ktkwIbU3jUUkPjhK/w+La4fx9F8YHFuMPTC X-Received: by 2002:a17:902:ceca:b0:177:fa1f:4abc with SMTP id d10-20020a170902ceca00b00177fa1f4abcmr940434plg.99.1665682463911; Thu, 13 Oct 2022 10:34:23 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1665682463; cv=none; d=google.com; s=arc-20160816; b=xyzWvjwFrSZ8rhM4xym1Yomj8kn4F2gNBakZ+ky+8t8kycwN5CDVnkB1Xgsobw2T1j VqqjLCsmzAloFQDwJP17d8ewrhcrsR5QTav6wdf0y8U7GJO9yuRxjOTgfzbDyQlHeX33 11RgadKOx54VdaBJtNoHtwtOmDYqwEUqKCPtZeXqmHkguj1YJsrZx5UtrRAva1FA1AN5 NINRjmtoOQsKw68ZGTO8wPDsdwd0s0C/wnvZdfrDdRfpVbRDPyP01AHUJTUr5rpUNVV9 VwcoGzoTgTOV+DHgzmK6dVKcw/QiGt+pRU4nSmtLMxIdmz+Ec4ZPFFYSW6j3Ks+2i+Bl ++kQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:content-transfer-encoding:mime-version :references:in-reply-to:message-id:date:subject:cc:to:from :dkim-signature:dkim-filter; bh=sf2YcBaC8BulfV1gLC66FnN/Vr7mvopLL1hXvmP/Wiw=; b=UOcN20a2Ozpba8ToW7Z63NhM9i6++tzgAITXyprwfqAmwtYojC1mkrj5jU39EXviIK QxEK+QQ/XVwUhcm40pZUHipLm0W6qgfVg6ar4U1y/hrftGPWWYSRbxm++jk7imoeeKvA AMo9e9YoFvdl1REjdNo/rhWw4zQcypMCunUoHe4S4/fq4FUOS0MJtYOreE33N9SU5mkD egaStY/h5rxwtZjqAvH6TmuUEqyy4LrkV6b3xLutjfQI1K+pHGqW0GXQhm+SnCPs8D2S eJ6BYFkFC6/yImD0jTzN5SluYsmfHX1nP+HqwPlXnXkbxYcV36iq/12SOJRvvJAJdlch r/+w== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@lwn.net header.s=20201203 header.b=FqTyH8aS; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: from out1.vger.email (out1.vger.email. [2620:137:e000::1:20]) by mx.google.com with ESMTP id eb25-20020a056a004c9900b00544e163575bsi20207963pfb.176.2022.10.13.10.34.08; Thu, 13 Oct 2022 10:34:23 -0700 (PDT) Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20; Authentication-Results: mx.google.com; dkim=pass header.i=@lwn.net header.s=20201203 header.b=FqTyH8aS; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229880AbiJMR3f (ORCPT + 99 others); Thu, 13 Oct 2022 13:29:35 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:48180 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229618AbiJMR31 (ORCPT ); Thu, 13 Oct 2022 13:29:27 -0400 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 3E805C3541; Thu, 13 Oct 2022 10:29:27 -0700 (PDT) Received: from meer.lwn.net (unknown [IPv6:2601:281:8300:73:8b7:7001:c8aa:b65f]) by ms.lwn.net (Postfix) with ESMTPA id CAB5A7DE; Thu, 13 Oct 2022 17:29:26 +0000 (UTC) DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net CAB5A7DE DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1665682167; bh=sf2YcBaC8BulfV1gLC66FnN/Vr7mvopLL1hXvmP/Wiw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=FqTyH8aSX2v/yn/lGIScRydi6QzAMazqsuDtDXFp4Tlpbs9GQggtulozm8WAnRhpR XVHtJwd1uAP6kBb1CGSe91z/O8NRNhy/4jbeyKTK2+8oF6v8WVmwIxqxnC2+CZdVQR E+UZcJyCDPWbj+VcnjnFlS0bWVWNY7wyafOXuA9B3CBpkTdehkbbvC8td7lSRf6Dgi doW6lPY/TXPwq57q9mw3ll4k8eP/wz+4Z7T0jPEeq9IVD8PJBF86aAQ6ToGozzlB24 3OiTsbGTpMH4KRAGzD8lI0zYBpy0vlbGFBp7sAGOGqBegzAhdgyktKAoPNQEwfwa3q /YvJYPTHWkNdA== From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org Subject: [PATCH v3 2/6] docs: tweak some Alabaster style parameters Date: Thu, 13 Oct 2022 11:29:14 -0600 Message-Id: <20221013172918.846856-3-corbet@lwn.net> X-Mailer: git-send-email 2.37.2 In-Reply-To: <20221013172918.846856-1-corbet@lwn.net> References: <20221013172918.846856-1-corbet@lwn.net> MIME-Version: 1.0 X-Spam-Status: No, score=-2.1 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,RCVD_IN_DNSWL_NONE, SPF_HELO_NONE,SPF_PASS autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on lindbergh.monkeyblade.net Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org X-getmail-retrieved-from-mailbox: =?utf-8?q?INBOX?= X-GMAIL-THRID: =?utf-8?q?1746594655165041405?= X-GMAIL-MSGID: =?utf-8?q?1746594655165041405?= This is just the beginning: tighten up the layout a bit to improve the information density in the browser. Also reconfigure the page width in terms of character units (em) rather than pixels, making it more display-independent. To that end, add a custom.css file to tweak Alabaster CSS settings. Acked-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/conf.py | 3 +++ Documentation/sphinx-static/custom.css | 14 ++++++++++++++ 2 files changed, 17 insertions(+) create mode 100644 Documentation/sphinx-static/custom.css diff --git a/Documentation/conf.py b/Documentation/conf.py index 629f4afeb0eb..1dbf3d6a55de 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -345,6 +345,9 @@ if html_theme == 'classic': else: html_theme_options = { 'description': get_cline_version(), + 'font_size': '10pt', + 'page_width': '65em', + 'sidebar_width': '15em', } sys.stderr.write("Using %s theme\n" % html_theme) diff --git a/Documentation/sphinx-static/custom.css b/Documentation/sphinx-static/custom.css new file mode 100644 index 000000000000..6b0e554cea0a --- /dev/null +++ b/Documentation/sphinx-static/custom.css @@ -0,0 +1,14 @@ +/* SPDX-License-Identifier: GPL-2.0 */ +/* + * CSS tweaks for the Alabaster theme + */ + +/* Shrink the headers a bit */ +div.body h1 { font-size: 180%; } +div.body h2 { font-size: 150%; } +div.body h3 { font-size: 130%; } + +/* Tighten up the layout slightly */ +div.body { padding: 0 15px 0 10px; } +div.document { margin: 20px 10px 0 10px; } +div.sphinxsidebarwrapper { padding: 1em 0.4em; } From patchwork Thu Oct 13 17:29:15 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jonathan Corbet X-Patchwork-Id: 2106 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a5d:4ac7:0:0:0:0:0 with SMTP id y7csp396289wrs; Thu, 13 Oct 2022 10:34:43 -0700 (PDT) X-Google-Smtp-Source: AMsMyM5SwoL9Pt5xOy/e4vp9BroaWo6gZUcvLlKfd22/LTikd4Bwvc+AwRngHh5WBPT5bYtT6hNl X-Received: by 2002:a17:90a:b103:b0:20d:69aa:a350 with SMTP id z3-20020a17090ab10300b0020d69aaa350mr12214611pjq.178.1665682483098; Thu, 13 Oct 2022 10:34:43 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1665682483; cv=none; d=google.com; s=arc-20160816; b=GKhtc43gL8NI8rZQq/5CO6YsPjLxkwka7SwaCgvKvYKwLpkwn1JscNj8RWdL4PN6rn emx+Mij69v+EUwCs7AoH4aATBjFhiQs9Fa07qcAklyWC54qtzvtj1hyT/2NEgKj2cQit djmW9VDhMbEgEcwvPhxmghlCwAdn1NYzdmPhbfhhsl0w3i0tRe8uYeIkMiUbGWiBv51J pjSFzHDEu4ZLRqp41kW2ZZn2JXcTW1NTagBCKwVZwl1iWNXAprOt6R1XGdEcXMZ5sXWM lnKuGJCbMtkFeKfYM11eb+0YcO35NRo2I3RvzUJd/wTOPuf3U8M1PHHTCXqhtUwS8rlo RHxw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:content-transfer-encoding:mime-version :references:in-reply-to:message-id:date:subject:cc:to:from :dkim-signature:dkim-filter; bh=yEUeV9l6CZglnt5o/00jB7iEk3jA2YvcWBl1vs8MpVQ=; b=v9xuPEVJaJNtiVVGiey5F7Qzb45n1sWwlSHurfYygsD85bs9tR6if/Wib4BD7kwNXf lWXjQRV9BaQFcJaqTJZQ+wKyKiwSpGormlnIusC6aaUVFF+B9//DlmL6SHhq+bTwW7lu XvxJayCGTmSlJzo7WkNSl6W+VmPhQ5gWqfQdcvdgC4UH5YOzDfxIaGEfRghdl668AOGC zQhB5ZiJkJstXIwW1iwl2aI7lgCrJ5Rck9GuNpkHTfGwyXu675RBwN32ilu6TU3tHEHD VbYu2F4OIcCJpp4TG44vmzda9Baa3ZTvlMt9y0UYlaqTeWoYk7BC3jePSwN8Gc1yI7fT Bvjg== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@lwn.net header.s=20201203 header.b="kQ/76cfq"; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: from out1.vger.email (out1.vger.email. [2620:137:e000::1:20]) by mx.google.com with ESMTP id c7-20020a634e07000000b0043417e65cb7si22853287pgb.347.2022.10.13.10.34.30; Thu, 13 Oct 2022 10:34:43 -0700 (PDT) Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20; Authentication-Results: mx.google.com; dkim=pass header.i=@lwn.net header.s=20201203 header.b="kQ/76cfq"; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229470AbiJMR3l (ORCPT + 99 others); Thu, 13 Oct 2022 13:29:41 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:48194 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229826AbiJMR32 (ORCPT ); Thu, 13 Oct 2022 13:29:28 -0400 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 93BECC4596; Thu, 13 Oct 2022 10:29:27 -0700 (PDT) Received: from meer.lwn.net (unknown [IPv6:2601:281:8300:73:8b7:7001:c8aa:b65f]) by ms.lwn.net (Postfix) with ESMTPA id 39824FFC; Thu, 13 Oct 2022 17:29:27 +0000 (UTC) DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 39824FFC DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1665682167; bh=yEUeV9l6CZglnt5o/00jB7iEk3jA2YvcWBl1vs8MpVQ=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=kQ/76cfqeiWt+/ntl+wRPAg76DOboVoSmkyfaVY10hUMrwYTj4zz6YzH7pc1f1G79 6mxKHNb9ZnWKg8RlniJqOkNonY2Knvf65DYz7mFa8Wgw+XKOUO0q6+T/e7juPdtr3h OgI/ezspfV4xdzlgGI3BnNBCWCYhqA1ff+EQRvWYyJD/lBOL6vxm4Tah57qlgI0RLX IyRpSm+8xzlAv9sxEePE2/9YzB/tRQqopR6WDA9rV0LOM2YwW2Qwvb2kfyAFtZsKhY 3qOe/zVIJZBkFA4fQSFmZQyAdPrXZsy7CLPZU3kG+32gXAQXFhwVJIweznzryQd7Yw ZkDvuZrK/VcTw== From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org Subject: [PATCH v3 3/6] docs: update sphinx.rst to reflect the default theme change Date: Thu, 13 Oct 2022 11:29:15 -0600 Message-Id: <20221013172918.846856-4-corbet@lwn.net> X-Mailer: git-send-email 2.37.2 In-Reply-To: <20221013172918.846856-1-corbet@lwn.net> References: <20221013172918.846856-1-corbet@lwn.net> MIME-Version: 1.0 X-Spam-Status: No, score=-2.1 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,RCVD_IN_DNSWL_NONE, SPF_HELO_NONE,SPF_PASS autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on lindbergh.monkeyblade.net Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org X-getmail-retrieved-from-mailbox: =?utf-8?q?INBOX?= X-GMAIL-THRID: =?utf-8?q?1746594675281525547?= X-GMAIL-MSGID: =?utf-8?q?1746594675281525547?= We don't default to Read The Docs anymore; update the docs to match. Acked-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/doc-guide/sphinx.rst | 16 +++++----------- 1 file changed, 5 insertions(+), 11 deletions(-) diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst index c708cec889af..23edb427e76f 100644 --- a/Documentation/doc-guide/sphinx.rst +++ b/Documentation/doc-guide/sphinx.rst @@ -147,11 +147,9 @@ section of ``make help``. The generated documentation is placed in format-specific subdirectories under ``Documentation/output``. To generate documentation, Sphinx (``sphinx-build``) must obviously be -installed. For prettier HTML output, the Read the Docs Sphinx theme -(``sphinx_rtd_theme``) is used if available. For PDF output you'll also need -``XeLaTeX`` and ``convert(1)`` from ImageMagick -(https://www.imagemagick.org).\ [#ink]_ -All of these are widely available and packaged in distributions. +installed. For PDF output you'll also need ``XeLaTeX`` and ``convert(1)`` +from ImageMagick (https://www.imagemagick.org).\ [#ink]_ All of these are +widely available and packaged in distributions. To pass extra options to Sphinx, you can use the ``SPHINXOPTS`` make variable. For example, use ``make SPHINXOPTS=-v htmldocs`` to get more verbose @@ -160,12 +158,8 @@ output. It is also possible to pass an extra DOCS_CSS overlay file, in order to customize the html layout, by using the ``DOCS_CSS`` make variable. -By default, the build will try to use the Read the Docs sphinx theme: - - https://github.com/readthedocs/sphinx_rtd_theme - -If the theme is not available, it will fall-back to the classic one. - +By default, the "Alabaster" theme is used to build the HTML documentation; +this theme is bundled with Sphinx and need not be installed separately. The Sphinx theme can be overridden by using the ``DOCS_THEME`` make variable. There is another make variable ``SPHINXDIRS``, which is useful when test From patchwork Thu Oct 13 17:29:16 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jonathan Corbet X-Patchwork-Id: 2112 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a5d:4ac7:0:0:0:0:0 with SMTP id y7csp397377wrs; Thu, 13 Oct 2022 10:37:10 -0700 (PDT) X-Google-Smtp-Source: AMsMyM7TrTHzEX/3K2Nm/Tosx68vk0o0r7b0BfBdO7auXnPrBaChBy5Sxt0QGl/WSl4+vTc1EYnN X-Received: by 2002:a17:906:8a64:b0:78d:b00d:fe with SMTP id hy4-20020a1709068a6400b0078db00d00femr680704ejc.32.1665682630770; Thu, 13 Oct 2022 10:37:10 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1665682630; cv=none; d=google.com; s=arc-20160816; b=B89QByF/k2ydBEohHa2OcLk+4UBHMMTXT5hk6nb0F1mBr9g3T3Jw6Nrh9lrNUN5br0 S5pIlGtObdV9un2qUP9W6V6KPGEwJqqbGqEABTbvGKv3GX9Buyd4uj1Nhy/sB278MQZ1 SSn5GARbsBAUC1R9OeaJuBEzljLY2e+qVa0bTA67K/WvNuJ7Wwch/jaN8LNx8XGdiWhd AbBIfPO8lf0js7W56KuWUTfKfJ1R7WkOgF1iLnhhzrEiGcSI+UZk1nQq6ZN5izVcC3OW X19EWWePK+7M2ENYjNe5XBCKrXQ53cGTnAJRUVTp0+8poAnsAgDpLCNa64+gH9RZO+Ym DZmg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:content-transfer-encoding:mime-version :references:in-reply-to:message-id:date:subject:cc:to:from :dkim-signature:dkim-filter; bh=w3wkfghYAXmRJrVxbzZZnrDjz+QM31pXF6acX37HbWw=; b=qY7CobIRh44+//LIx8ZM4nkMnI6Zyu2SleyS7kD8/pR/pwtpusbeqJQe0c3O2UmzyM AQewOdykkeWyRsQFeAP4Q7cjQr5tFs/lrMwB7zuJZGMYQLfCeQCndJ5xjxTb6wtzs3rB VevqvlZKD/ykMqKaDBlRCZuq4LlXVs4Xy6CuW723RKBpI7CeqIqoJbBhPsz6lzHZ9jhO OEALRRvdXMiT0CztEDuRYNphRHzt0K6tnzh9NN1v5tSURpRApURkMIXjJfzIAeiWV/JV 8EPArNoiJqZhORs6LNaaJza6B9HNm0eFPyyXVGyFYN7MPMHPyMEkpv2zv5Hw6Ru7Yy5i 5Ebg== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@lwn.net header.s=20201203 header.b=D3GqwBum; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: from out1.vger.email (out1.vger.email. [2620:137:e000::1:20]) by mx.google.com with ESMTP id cr13-20020a170906d54d00b00779e6c93108si218915ejc.598.2022.10.13.10.36.45; Thu, 13 Oct 2022 10:37:10 -0700 (PDT) Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20; Authentication-Results: mx.google.com; dkim=pass header.i=@lwn.net header.s=20201203 header.b=D3GqwBum; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229905AbiJMR3q (ORCPT + 99 others); Thu, 13 Oct 2022 13:29:46 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:48206 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229833AbiJMR32 (ORCPT ); Thu, 13 Oct 2022 13:29:28 -0400 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id F35C5C34E3; Thu, 13 Oct 2022 10:29:27 -0700 (PDT) Received: from meer.lwn.net (unknown [IPv6:2601:281:8300:73:8b7:7001:c8aa:b65f]) by ms.lwn.net (Postfix) with ESMTPA id 9186D7F9; Thu, 13 Oct 2022 17:29:27 +0000 (UTC) DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 9186D7F9 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1665682167; bh=w3wkfghYAXmRJrVxbzZZnrDjz+QM31pXF6acX37HbWw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=D3GqwBumdV9U5+dZCyn903icHDcZ0uZ7BAbUH5iFPTIHMBLomaKDd69BNFNW7PfGG KEoM+skcQbCegEuK9EwC9MS38pqVyAzTaDZHPogH4+svnQa+gqCt1iAWdXT7DCmrdg Vsz52LzlkcBtb+2noB22zVdhcMKgBEzHHFJNcMieCXYq51EZMgkqcPra4txdQAVYJm IXk+y3mBY1wp0OpPUALKP7IS+53CFl6TydYVrQYgawRqtq77ews1PeSS9Ygvf2rvPL TCLoVGs3uL+l0UNXW04tNjUsUbqOYwkUoRfzQJsVs+kECN/rHigQcwUNjgYjK51Xa7 ZDNXCfqjGT8rw== From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org Subject: [PATCH v3 4/6] docs: sphinx-pre-install: don't require the RTD theme Date: Thu, 13 Oct 2022 11:29:16 -0600 Message-Id: <20221013172918.846856-5-corbet@lwn.net> X-Mailer: git-send-email 2.37.2 In-Reply-To: <20221013172918.846856-1-corbet@lwn.net> References: <20221013172918.846856-1-corbet@lwn.net> MIME-Version: 1.0 X-Spam-Status: No, score=-2.1 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,RCVD_IN_DNSWL_NONE, SPF_HELO_NONE,SPF_PASS autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on lindbergh.monkeyblade.net Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org X-getmail-retrieved-from-mailbox: =?utf-8?q?INBOX?= X-GMAIL-THRID: =?utf-8?q?1746594830338830900?= X-GMAIL-MSGID: =?utf-8?q?1746594830338830900?= We don't default to the RTD theme anymore, so sphinx-pre-install need not insist on installing it. Acked-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/sphinx/requirements.txt | 1 - scripts/sphinx-pre-install | 8 -------- 2 files changed, 9 deletions(-) diff --git a/Documentation/sphinx/requirements.txt b/Documentation/sphinx/requirements.txt index 2c573541ab71..335b53df35e2 100644 --- a/Documentation/sphinx/requirements.txt +++ b/Documentation/sphinx/requirements.txt @@ -1,4 +1,3 @@ # jinja2>=3.1 is not compatible with Sphinx<4.0 jinja2<3.1 -sphinx_rtd_theme Sphinx==2.4.4 diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install index ec84fc62774e..1fb88fdceec3 100755 --- a/scripts/sphinx-pre-install +++ b/scripts/sphinx-pre-install @@ -362,7 +362,6 @@ sub give_debian_hints() { my %map = ( "python-sphinx" => "python3-sphinx", - "sphinx_rtd_theme" => "python3-sphinx-rtd-theme", "ensurepip" => "python3-venv", "virtualenv" => "virtualenv", "dot" => "graphviz", @@ -397,7 +396,6 @@ sub give_redhat_hints() { my %map = ( "python-sphinx" => "python3-sphinx", - "sphinx_rtd_theme" => "python3-sphinx_rtd_theme", "virtualenv" => "python3-virtualenv", "dot" => "graphviz", "convert" => "ImageMagick", @@ -475,7 +473,6 @@ sub give_opensuse_hints() { my %map = ( "python-sphinx" => "python3-sphinx", - "sphinx_rtd_theme" => "python3-sphinx_rtd_theme", "virtualenv" => "python3-virtualenv", "dot" => "graphviz", "convert" => "ImageMagick", @@ -523,7 +520,6 @@ sub give_mageia_hints() { my %map = ( "python-sphinx" => "python3-sphinx", - "sphinx_rtd_theme" => "python3-sphinx_rtd_theme", "virtualenv" => "python3-virtualenv", "dot" => "graphviz", "convert" => "ImageMagick", @@ -567,7 +563,6 @@ sub give_mageia_hints() sub give_arch_linux_hints() { my %map = ( - "sphinx_rtd_theme" => "python-sphinx_rtd_theme", "virtualenv" => "python-virtualenv", "dot" => "graphviz", "convert" => "imagemagick", @@ -598,7 +593,6 @@ sub give_arch_linux_hints() sub give_gentoo_hints() { my %map = ( - "sphinx_rtd_theme" => "dev-python/sphinx_rtd_theme", "virtualenv" => "dev-python/virtualenv", "dot" => "media-gfx/graphviz", "convert" => "media-gfx/imagemagick", @@ -895,7 +889,6 @@ sub recommend_sphinx_version($) $verbose_warn_install = 0; add_package("python-sphinx", 0); - check_python_module("sphinx_rtd_theme", 1); check_distros(); @@ -968,7 +961,6 @@ sub check_needs() check_perl_module("Pod::Usage", 0); check_program("make", 0); check_program("gcc", 0); - check_python_module("sphinx_rtd_theme", 1) if (!$virtualenv); check_program("dot", 1); check_program("convert", 1); From patchwork Thu Oct 13 17:29:17 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jonathan Corbet X-Patchwork-Id: 2111 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a5d:4ac7:0:0:0:0:0 with SMTP id y7csp397281wrs; Thu, 13 Oct 2022 10:36:58 -0700 (PDT) X-Google-Smtp-Source: AMsMyM73hOnzLAMUggR+ma6lsMX0T6k6iXzFr4HTjipTN5VGphTPp5uk62Bx4J3nFeX9E9GjY6zD X-Received: by 2002:a17:903:1207:b0:185:4042:23d2 with SMTP id l7-20020a170903120700b00185404223d2mr101867plh.143.1665682618251; Thu, 13 Oct 2022 10:36:58 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1665682618; cv=none; d=google.com; s=arc-20160816; b=GV5+cxeMlA4w3fv2gZRafUsfpSlU5Npdz9opq4R4hRP9yF7TvE1oNbKOrLZ0nB7oDo 9mCKDAJDJVR+NCREkb+2rLo3VlRJxpDdAqdL4Ps9QDIIMEImnXSab5LWgo4qjR1za48J aIcz18h8wkFcsxxzwi9/eFEobdL/wrMhPMUm+AA6fz5Rl2E9B5G5HB7TpOXr/ey6ibA5 oNAiqKxn+5zqLe8jy/3OUJ+CAxaeYy87KuyUV9PqthxrpjEdvp395W0/OZsRfayR53ni P07rL2In2W/t12zhztjrQkptSN0tfNIWJDetOHIWB9d22nieLD9vAV5+J8FGcQfddJD4 Xthw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:content-transfer-encoding:mime-version :references:in-reply-to:message-id:date:subject:cc:to:from :dkim-signature:dkim-filter; bh=0opHrZqvXrL6VtcOxiAU4dw/b0sguVWD5kn6y9m/afo=; b=BZOmz21rLOAI2WTUyUobSzF9ETflSLWfPGXySo70/E81Xji0N/0BHJHAZFJdmtMeHb pse7GUC2dqcs8vaW2NoLLmGqJo73DbuqYZVXhFsxraDAdWx5ZXYowZHE7rhqY85RRRoM CRzvwR7f7CdPFImbgDujL3qoh2JyFwPIm8RJyGg+j+6TsL8xiyI85LeJCG/43V/DN8P1 Q2xnVESdM/sEaCiGPRObQnOe4TAJq9Ivlm2CNMhiXAl9761dHhP6hDFIgDZUlbg/KuOZ pdYgoAsL6SmQ1NLODItwCr25m/Gx5Kmlxy8yOID1xlrpKgpmkDbzMCkdfbLZQU3eYXib 9aLA== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@lwn.net header.s=20201203 header.b=CzbjjyF5; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: from out1.vger.email (out1.vger.email. [2620:137:e000::1:20]) by mx.google.com with ESMTP id a3-20020a170902ecc300b0017a0a6b5b11si394560plh.145.2022.10.13.10.36.45; Thu, 13 Oct 2022 10:36:58 -0700 (PDT) Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20; Authentication-Results: mx.google.com; dkim=pass header.i=@lwn.net header.s=20201203 header.b=CzbjjyF5; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229920AbiJMR3v (ORCPT + 99 others); Thu, 13 Oct 2022 13:29:51 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:48212 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229846AbiJMR33 (ORCPT ); Thu, 13 Oct 2022 13:29:29 -0400 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 611CDC3541; Thu, 13 Oct 2022 10:29:28 -0700 (PDT) Received: from meer.lwn.net (unknown [IPv6:2601:281:8300:73:8b7:7001:c8aa:b65f]) by ms.lwn.net (Postfix) with ESMTPA id E49D9845; Thu, 13 Oct 2022 17:29:27 +0000 (UTC) DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net E49D9845 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1665682168; bh=0opHrZqvXrL6VtcOxiAU4dw/b0sguVWD5kn6y9m/afo=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=CzbjjyF5THDuiifk7pwCcR2BT3lwHJ1v5ySNvbHfr+iosLF/ruylselyA+DC2cr7k weO48FqSQpscOjHUOaMT0rande9wdUNRhRwmwrfsuyNC61y2XEgDygTxApMMj73Xv3 YTx5SpYKE1hI0hkKu6n31+T8rKqr0JJ0uLHVelp+xg7qFM07Sc3WnKvUHbWf7VK38d KXVvscZ1f3llbQC9dVR6YS+LrcL7+bVd6Xmm9HmocARTEiEIOriAgKhD2GYGrddIJ/ DdcHJCEcCo0eizwMAXzE0CpwT/e7OBGYCcxU5bvrZZ4j4pFXPVhxBPx7wqkEAvFw1K 6PVo4JdcFzIXQ== From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org Subject: [PATCH v3 5/6] docs: improve the HTML formatting of kerneldoc comments Date: Thu, 13 Oct 2022 11:29:17 -0600 Message-Id: <20221013172918.846856-6-corbet@lwn.net> X-Mailer: git-send-email 2.37.2 In-Reply-To: <20221013172918.846856-1-corbet@lwn.net> References: <20221013172918.846856-1-corbet@lwn.net> MIME-Version: 1.0 X-Spam-Status: No, score=-2.1 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,RCVD_IN_DNSWL_NONE, SPF_HELO_NONE,SPF_PASS autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on lindbergh.monkeyblade.net Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org X-getmail-retrieved-from-mailbox: =?utf-8?q?INBOX?= X-GMAIL-THRID: =?utf-8?q?1746594817194573527?= X-GMAIL-MSGID: =?utf-8?q?1746594817194573527?= Make a few changes to cause functions documented by kerneldoc to stand out better in the rendered documentation. Specifically, change kernel-doc to put the description section into a ".. container::" section, then add a bit of CSS to indent that section relative to the function prototype (or struct or enum definition). Tweak a few other CSS parameters while in the neighborhood to improve the formatting. Acked-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/sphinx-static/custom.css | 16 +++++++- scripts/kernel-doc | 52 ++++++++++++++++---------- 2 files changed, 47 insertions(+), 21 deletions(-) diff --git a/Documentation/sphinx-static/custom.css b/Documentation/sphinx-static/custom.css index 6b0e554cea0a..9b36f7abd24f 100644 --- a/Documentation/sphinx-static/custom.css +++ b/Documentation/sphinx-static/custom.css @@ -10,5 +10,19 @@ div.body h3 { font-size: 130%; } /* Tighten up the layout slightly */ div.body { padding: 0 15px 0 10px; } -div.document { margin: 20px 10px 0 10px; } div.sphinxsidebarwrapper { padding: 1em 0.4em; } +/* Tweak document margins and don't force width */ +div.document { + margin: 20px 10px 0 10px; + width: auto; +} + +/* + * Parameters for the display of function prototypes and such included + * from C source files. + */ +dl.function, dl.struct, dl.enum { margin-top: 2em; background-color: #ecf0f3; } +/* indent lines 2+ of multi-line function prototypes */ +dl.function dt { margin-left: 10em; text-indent: -10em; } +dt.sig-object { font-size: larger; } +div.kernelindent { margin-left: 2em; margin-right: 4em; } diff --git a/scripts/kernel-doc b/scripts/kernel-doc index aea04365bc69..85ea80fb5154 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -866,48 +866,53 @@ sub output_function_rst(%) { print "\n"; } - print "**Parameters**\n\n"; + # + # Put our descriptive text into a container (thus an HTML
) to help + # set the function prototypes apart. + # + print ".. container:: kernelindent\n\n"; $lineprefix = " "; + print $lineprefix . "**Parameters**\n\n"; foreach $parameter (@{$args{'parameterlist'}}) { my $parameter_name = $parameter; $parameter_name =~ s/\[.*//; $type = $args{'parametertypes'}{$parameter}; if ($type ne "") { - print "``$type``\n"; + print $lineprefix . "``$type``\n"; } else { - print "``$parameter``\n"; + print $lineprefix . "``$parameter``\n"; } print_lineno($parameterdesc_start_lines{$parameter_name}); + $lineprefix = " "; if (defined($args{'parameterdescs'}{$parameter_name}) && $args{'parameterdescs'}{$parameter_name} ne $undescribed) { output_highlight_rst($args{'parameterdescs'}{$parameter_name}); } else { - print " *undescribed*\n"; + print $lineprefix . "*undescribed*\n"; } + $lineprefix = " "; print "\n"; } - $lineprefix = $oldprefix; output_section_rst(@_); + $lineprefix = $oldprefix; } sub output_section_rst(%) { my %args = %{$_[0]}; my $section; my $oldprefix = $lineprefix; - $lineprefix = ""; foreach $section (@{$args{'sectionlist'}}) { - print "**$section**\n\n"; + print $lineprefix . "**$section**\n\n"; print_lineno($section_start_lines{$section}); output_highlight_rst($args{'sections'}{$section}); print "\n"; } print "\n"; - $lineprefix = $oldprefix; } sub output_enum_rst(%) { @@ -915,6 +920,7 @@ sub output_enum_rst(%) { my ($parameter); my $oldprefix = $lineprefix; my $count; + my $outer; if ($sphinx_major < 3) { my $name = "enum " . $args{'enum'}; @@ -924,14 +930,17 @@ sub output_enum_rst(%) { print "\n\n.. c:enum:: " . $name . "\n\n"; } print_lineno($declaration_start_line); - $lineprefix = " "; + $lineprefix = " "; output_highlight_rst($args{'purpose'}); print "\n"; - print "**Constants**\n\n"; - $lineprefix = " "; + print ".. container:: kernelindent\n\n"; + $outer = $lineprefix . " "; + $lineprefix = $outer . " "; + print $outer . "**Constants**\n\n"; foreach $parameter (@{$args{'parameterlist'}}) { - print "``$parameter``\n"; + print $outer . "``$parameter``\n"; + if ($args{'parameterdescs'}{$parameter} ne $undescribed) { output_highlight_rst($args{'parameterdescs'}{$parameter}); } else { @@ -939,7 +948,7 @@ sub output_enum_rst(%) { } print "\n"; } - + print "\n"; $lineprefix = $oldprefix; output_section_rst(@_); } @@ -982,18 +991,19 @@ sub output_struct_rst(%) { } } print_lineno($declaration_start_line); - $lineprefix = " "; + $lineprefix = " "; output_highlight_rst($args{'purpose'}); print "\n"; - print "**Definition**\n\n"; - print "::\n\n"; + print ".. container:: kernelindent\n\n"; + print $lineprefix . "**Definition**::\n\n"; my $declaration = $args{'definition'}; - $declaration =~ s/\t/ /g; - print " " . $args{'type'} . " " . $args{'struct'} . " {\n$declaration };\n\n"; + $lineprefix = $lineprefix . " "; + $declaration =~ s/\t/$lineprefix/g; + print $lineprefix . $args{'type'} . " " . $args{'struct'} . " {\n$declaration" . $lineprefix . "};\n\n"; - print "**Members**\n\n"; $lineprefix = " "; + print $lineprefix . "**Members**\n\n"; foreach $parameter (@{$args{'parameterlist'}}) { ($parameter =~ /^#/) && next; @@ -1003,8 +1013,10 @@ sub output_struct_rst(%) { ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; $type = $args{'parametertypes'}{$parameter}; print_lineno($parameterdesc_start_lines{$parameter_name}); - print "``" . $parameter . "``\n"; + print $lineprefix . "``" . $parameter . "``\n"; + $lineprefix = " "; output_highlight_rst($args{'parameterdescs'}{$parameter_name}); + $lineprefix = " "; print "\n"; } print "\n"; From patchwork Thu Oct 13 17:29:18 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jonathan Corbet X-Patchwork-Id: 2107 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a5d:4ac7:0:0:0:0:0 with SMTP id y7csp396463wrs; Thu, 13 Oct 2022 10:35:07 -0700 (PDT) X-Google-Smtp-Source: AMsMyM6O+PK9/ySrpJ5IDPFQP2I8fXmLrpikrjP7koE0upXbU+zJ+p0gZYHHoIAqPn/yMcHSpT87 X-Received: by 2002:a17:902:f64f:b0:179:edcc:2bf4 with SMTP id m15-20020a170902f64f00b00179edcc2bf4mr856482plg.70.1665682507544; Thu, 13 Oct 2022 10:35:07 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1665682507; cv=none; d=google.com; s=arc-20160816; b=O37ZOrj+NvU90hWVax19mZE5CXdVJ15+HUJgM0AjPG4dp/GlIReKeuI1OVIJXmTOKx 4vHen+lkHQLbAwke1BeEjQq497D3xXN6Sn3UskhUncd/4gdfBjr3a1kLZrF1PEs7x6q0 diCBwuOO2+AnqdM8uAsY5McVygXBqDnbp8GbFNp8o8dA/Y0b79muS6ADVwggkf4i5Y3U plysSRXARBgltWKzgLRLjDxJbfqlCOHcM4PFjvC8yhitHuf42jFHmGFLS8VHiwKpOTA2 bLc0QWlz7lmPhgu24y4qx1ZWwDwN41fY/sH3JsycNkDW0EmC0DPMILwAPMsYz9qu7RvF K0XQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:content-transfer-encoding:mime-version :references:in-reply-to:message-id:date:subject:cc:to:from :dkim-signature:dkim-filter; bh=keh3BAATlkR8yDL2srU6MNeKVExwzXPbSFhQxtmEIdk=; b=VADkD2w68Ah5+sgKoRkjpE35+ctblVUoQJcEf8hT7DIGByYfwEdUCx2GGawh1WTCIB I0/cmt32tuzftOEx+Fz2OZI7ia9hfqnn9HlhHiKgApiBHPOFOYnr/BPTd5PtrBkoVRbW 7ry1LrAMbr1810mC6OrAzjpN0oT/xhTZKaycURdqRLvPrCD1MW1AcNiYBNbzsm47B5ou fAIUgGg4huAWKCpaJO4jWXCZah8+MFn7itBVbxfScPrzuHe6JunmgTUD3gfJdg0MXgLm qYH/COyg4NxPNleTXRn5JEAQkMX0yHHD00L1xlkcJxZ2UV654LgSzgg9NMqaUY7M13K5 YS0Q== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@lwn.net header.s=20201203 header.b=s332vN68; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: from out1.vger.email (out1.vger.email. [2620:137:e000::1:20]) by mx.google.com with ESMTP id e23-20020a656897000000b0046b08e97d2asi2177031pgt.681.2022.10.13.10.34.54; Thu, 13 Oct 2022 10:35:07 -0700 (PDT) Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20; Authentication-Results: mx.google.com; dkim=pass header.i=@lwn.net header.s=20201203 header.b=s332vN68; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229947AbiJMR35 (ORCPT + 99 others); Thu, 13 Oct 2022 13:29:57 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:48218 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229861AbiJMR3a (ORCPT ); Thu, 13 Oct 2022 13:29:30 -0400 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id C0E61D038E; Thu, 13 Oct 2022 10:29:28 -0700 (PDT) Received: from meer.lwn.net (unknown [IPv6:2601:281:8300:73:8b7:7001:c8aa:b65f]) by ms.lwn.net (Postfix) with ESMTPA id 44F0C7DE; Thu, 13 Oct 2022 17:29:28 +0000 (UTC) DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 44F0C7DE DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1665682168; bh=keh3BAATlkR8yDL2srU6MNeKVExwzXPbSFhQxtmEIdk=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=s332vN68n3jqb2xYS+ZyYgEsAFrNsqsWuUvhcbLuNPL0CzQXC+PVGOSKII3104BSk l1SzFbQdQGXojU0xubGNluP7x9pCPqnCpf9x2Jf2wuSs9ucB951+ByUhA6n65n6Yge bZJYhrg7rgIKOPue9b882fj8UBGLN1Ll52ZEXq+2WFy1KQgJ6JrWWsJ1vBwf6ByQYU aB4HswMJiJfBXIG6ipVKRzmEEgR5lsQxC0mrOtbFX4UUrs6Tk/HOi3BxXLN2Bs/ad3 3yBSA5XOvk4gRhiKgA5ZXHnA/YJobyYqpmQWa4/krZ4VRu8ULQJNuJsJtTR+Yyc22B 1InmJOhTu3B5w== From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org Subject: [PATCH v3 6/6] docs: decruft Documentation/conf.py Date: Thu, 13 Oct 2022 11:29:18 -0600 Message-Id: <20221013172918.846856-7-corbet@lwn.net> X-Mailer: git-send-email 2.37.2 In-Reply-To: <20221013172918.846856-1-corbet@lwn.net> References: <20221013172918.846856-1-corbet@lwn.net> MIME-Version: 1.0 X-Spam-Status: No, score=-2.1 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,RCVD_IN_DNSWL_NONE, SPF_HELO_NONE,SPF_PASS autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on lindbergh.monkeyblade.net Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org X-getmail-retrieved-from-mailbox: =?utf-8?q?INBOX?= X-GMAIL-THRID: =?utf-8?q?1746594700826628360?= X-GMAIL-MSGID: =?utf-8?q?1746594700826628360?= Remove the ancient support for the Sphinx "classic" theme; everybody will have alabaster, so that fallback is no longer needed. While in the neighborhood: get rid of lots of useless comment lines. They describe the state of Sphinx options when we first created that file and are just clutter now. Suggested-by: Mauro Carvalho Chehab Acked-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/conf.py | 181 +----------------------------------------- 1 file changed, 2 insertions(+), 179 deletions(-) diff --git a/Documentation/conf.py b/Documentation/conf.py index 1dbf3d6a55de..6ab47833ab6c 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -297,7 +297,7 @@ if html_theme == 'sphinx_rtd_theme' or html_theme == 'sphinx_rtd_dark_mode': html_css_files.append('theme_rtd_colors.css') except ImportError: - html_theme = 'classic' + html_theme = 'alabaster' if "DOCS_CSS" in os.environ: css = os.environ["DOCS_CSS"].split(" ") @@ -313,36 +313,7 @@ if major <= 1 and minor < 8: for l in html_css_files: html_context['css_files'].append('_static/' + l) -if html_theme == 'classic': - html_theme_options = { - 'rightsidebar': False, - 'stickysidebar': True, - 'collapsiblesidebar': True, - 'externalrefs': False, - - 'footerbgcolor': "white", - 'footertextcolor': "white", - 'sidebarbgcolor': "white", - 'sidebarbtncolor': "black", - 'sidebartextcolor': "black", - 'sidebarlinkcolor': "#686bff", - 'relbarbgcolor': "#133f52", - 'relbartextcolor': "white", - 'relbarlinkcolor': "white", - 'bgcolor': "white", - 'textcolor': "black", - 'headbgcolor': "#f2f2f2", - 'headtextcolor': "#20435c", - 'headlinkcolor': "#c60f0f", - 'linkcolor': "#355f7c", - 'visitedlinkcolor': "#355f7c", - 'codebgcolor': "#3f3f3f", - 'codetextcolor': "white", - - 'bodyfont': "serif", - 'headfont': "sans-serif", - } -else: +if html_theme == 'alabaster': html_theme_options = { 'description': get_cline_version(), 'font_size': '10pt', @@ -352,44 +323,11 @@ else: sys.stderr.write("Using %s theme\n" % html_theme) -# 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 -# documentation. -#html_theme_options = {} - -# Add any paths that contain custom themes here, relative to this directory. -#html_theme_path = [] - -# The name for this set of Sphinx documents. If None, it defaults to -# " v documentation". -#html_title = None - -# A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -#html_logo = None - -# 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 - # 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 = ['sphinx-static'] -# Add any extra paths that contain custom files (such as robots.txt or -# .htaccess) here, relative to this directory. These files are copied -# directly to the root of the documentation. -#html_extra_path = [] - -# 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' - # If true, SmartyPants will be used to convert quotes and dashes to # typographically correct entities. html_use_smartypants = False @@ -398,50 +336,6 @@ html_use_smartypants = False # Note that the RTD theme ignores this html_sidebars = { '**': ["about.html", 'searchbox.html', 'localtoc.html', 'sourcelink.html']} -# Additional templates that should be rendered to pages, maps page names to -# template names. -#html_additional_pages = {} - -# If false, no module index is generated. -#html_domain_indices = True - -# If false, no index is generated. -#html_use_index = True - -# If true, the index is split into individual pages for each letter. -#html_split_index = False - -# If true, links to the reST sources are added to the pages. -#html_show_sourcelink = True - -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -#html_show_sphinx = True - -# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -#html_show_copyright = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -#html_use_opensearch = '' - -# This is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = None - -# Language to be used for generating the HTML full-text search index. -# Sphinx supports the following languages: -# 'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja' -# 'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr' -#html_search_language = 'en' - -# A dictionary with options for the search language support, empty by default. -# Now only 'ja' uses this config value -#html_search_options = {'type': 'default'} - -# The name of a javascript file (relative to the configuration directory) that -# implements a search results scorer. If empty, the default will be used. -#html_search_scorer = 'scorer.js' - # Output file base name for HTML help builder. htmlhelp_basename = 'TheLinuxKerneldoc' @@ -583,19 +477,6 @@ texinfo_documents = [ 'Miscellaneous'), ] -# Documents to append as an appendix to all manuals. -#texinfo_appendices = [] - -# If false, no module index is generated. -#texinfo_domain_indices = True - -# How to display URL addresses: 'footnote', 'no', or 'inline'. -#texinfo_show_urls = 'footnote' - -# If true, do not generate a @detailmenu in the "Top" node's menu. -#texinfo_no_detailmenu = False - - # -- Options for Epub output ---------------------------------------------- # Bibliographic Dublin Core info. @@ -604,67 +485,9 @@ epub_author = author epub_publisher = author epub_copyright = copyright -# The basename for the epub file. It defaults to the project name. -#epub_basename = project - -# The HTML theme for the epub output. Since the default themes are not -# optimized for small screen space, using the same theme for HTML and epub -# output is usually not wise. This defaults to 'epub', a theme designed to save -# visual space. -#epub_theme = 'epub' - -# The language of the text. It defaults to the language option -# or 'en' if the language is not set. -#epub_language = '' - -# The scheme of the identifier. Typical schemes are ISBN or URL. -#epub_scheme = '' - -# The unique identifier of the text. This can be a ISBN number -# or the project homepage. -#epub_identifier = '' - -# A unique identification for the text. -#epub_uid = '' - -# A tuple containing the cover image and cover page html template filenames. -#epub_cover = () - -# A sequence of (type, uri, title) tuples for the guide element of content.opf. -#epub_guide = () - -# HTML files that should be inserted before the pages created by sphinx. -# The format is a list of tuples containing the path and title. -#epub_pre_files = [] - -# HTML files that should be inserted after the pages created by sphinx. -# The format is a list of tuples containing the path and title. -#epub_post_files = [] - # A list of files that should not be packed into the epub file. epub_exclude_files = ['search.html'] -# The depth of the table of contents in toc.ncx. -#epub_tocdepth = 3 - -# Allow duplicate toc entries. -#epub_tocdup = True - -# Choose between 'default' and 'includehidden'. -#epub_tocscope = 'default' - -# Fix unsupported image types using the Pillow. -#epub_fix_images = False - -# Scale large images. -#epub_max_image_width = 0 - -# How to display URL addresses: 'footnote', 'no', or 'inline'. -#epub_show_urls = 'inline' - -# If false, no index is generated. -#epub_use_index = True - #======= # rst2pdf #