From patchwork Sun Mar 12 20:17:12 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Joe Stringer X-Patchwork-Id: 68564 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a5d:5915:0:0:0:0:0 with SMTP id v21csp863994wrd; Sun, 12 Mar 2023 13:26:22 -0700 (PDT) X-Google-Smtp-Source: AK7set/UV3XCeZ64apzJdPky7e4EbNqCF1Mh8pfsEaJ89uABtLswHcElaVcrYlVpbbniIPyQRHyI X-Received: by 2002:a17:90b:384f:b0:230:c723:f37d with SMTP id nl15-20020a17090b384f00b00230c723f37dmr32247333pjb.40.1678652782095; Sun, 12 Mar 2023 13:26:22 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1678652782; cv=none; d=google.com; s=arc-20160816; b=NgPXBuO1lvAWb5ssLtBoV9oe2fYgusdFUtF7ka5eBxCQddDexf6huLYtO1CZ+Mwmmf LvNvyNmM7xqhIcIZ1KjGyVknJ50eYK//0u5cpnGqlyzLE0qhry6LE9C4X0dUiojCNBj3 2zzlsx20yid3TM3XxSlOwwJYkPe2teRpQKEyTWhN7EXOpRft2aUMb/zuO3oJrSa1OKdS KQmTkP/j8mfcdu06+nk30QacnvPvDv8bgn0cD5OHksdakwkcp01I2oWHjMk+hh8fgexu +FYEfJtupehs2jD8cps4RBEbyE6eaeJ0EWgelME++ANRBfU4Yzh30/X37uuwg/7j88NB vSdQ== 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 :message-id:date:subject:cc:to:from:dkim-signature; bh=Ci1g5tAeDNBEuhH1jXrQ1uQStWKKV42Sr6cMMYRU68c=; b=xd1cbG3Jthsng+DlulYwAr+Iy6AmGj0vHm4hIIGVn4ak3KylN9ry15HNqdN9pUk6l/ aYKf8rFKK2yO3qrbbLeUXF6HSchg3fx5ru3mafH4aQYRDKoCTpiMQRsI5NouWmkygvWB m7PoTh+AqkmvLL+RZxj1QrmxY78IVtbQ6XS7jx9MAWh/qp/gIWXgXL8oZFPhtTd4/rCQ IN6DZTvKDrJ/iuZDk9RBntXS7EkvHlEjlva+jc2MSJeTiCkZRvD6xpScKH7B/dj11tr3 7twOchpQYmukaHoGVyii7NqteCg+C0QhgjCw/kVfd4PZU0hMpSEZeGZ9hpbQyrNdZp46 sBAw== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@isovalent.com header.s=google header.b=Te7Sj25L; 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; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=isovalent.com Received: from out1.vger.email (out1.vger.email. [2620:137:e000::1:20]) by mx.google.com with ESMTP id il11-20020a17090b164b00b00230c82c6284si5271335pjb.19.2023.03.12.13.26.07; Sun, 12 Mar 2023 13:26:22 -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=@isovalent.com header.s=google header.b=Te7Sj25L; 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; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=isovalent.com Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S230230AbjCLURY (ORCPT + 99 others); Sun, 12 Mar 2023 16:17:24 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:49758 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229829AbjCLURW (ORCPT ); Sun, 12 Mar 2023 16:17:22 -0400 Received: from mail-pj1-x1034.google.com (mail-pj1-x1034.google.com [IPv6:2607:f8b0:4864:20::1034]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 278801CF69 for ; Sun, 12 Mar 2023 13:17:21 -0700 (PDT) Received: by mail-pj1-x1034.google.com with SMTP id u3-20020a17090a450300b00239db6d7d47so9698163pjg.4 for ; Sun, 12 Mar 2023 13:17:21 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=isovalent.com; s=google; t=1678652240; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:from:to:cc:subject:date:message-id:reply-to; bh=Ci1g5tAeDNBEuhH1jXrQ1uQStWKKV42Sr6cMMYRU68c=; b=Te7Sj25L1Xre20HX7AR3yNOJBn+TmyS/B8aNWc3DC3+6WChcR747mbVq0AFAXsftx1 Md9JZM/7IiSc3gxOn7PsExubTw65bvGF4FKnStN23TaegwMI4XqKbGjxjHlOntc9WP+V E4owFYDhSzmhvgNqx3M84PM6SIAzOjJLViN0bnIhOuH6JfxfRgqfP4gf/XYa/55ahRGV 7aQw6Z47A/0WyN2ZK4JsU4dIqgZAuD33cF2R5wQmhZnZZ9kGSHiRaJkT6Y1I/JqA4I/y WCoKb0pHlNlweTncqqRHSvAQ/eIcbi5Ilw9vRdocasujmJtqIOidhFWRsehAtNkDTt5v ZXFQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; t=1678652240; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=Ci1g5tAeDNBEuhH1jXrQ1uQStWKKV42Sr6cMMYRU68c=; b=N8WGgMhf/fcLp6aAt0IRHnvZF1YZNaFb2Lm9i+GdxCh1uGojfd5twkUxFw0hsRgrUp +2m9Z0wBS97Sskq9sufj9MzXGObzzhfvaHfPBFipzELYiJ+qkUin+7Zvxl5pGs1CJ7rf P4fSpfmEITlhsWPGe1M58d69LsxkHoyUfQA5i4bKO3h+/vMoLmTFFIA9gGOixeAgNoL0 c+vqIb3xZxSHhsQByIHFGL8u20VKigwseZYbW6Stxrm4YHd3yvU4MdCF1KwOh+J7HKtV qmETXMpysm4AvhhHPFcZLlLrNADAFf3vriN5RWa87dI4mNgn+Oiih2zaCG74dND9tGfg Dvhg== X-Gm-Message-State: AO0yUKXVRJ10AGpRbgGcx4L06k/vToIAaENY97O9lb4bjWFfZCO+2QDB wuP+N+bnAl24w6fiiE168+Ttn4N5vYz3HRMLGqY= X-Received: by 2002:a17:903:244f:b0:1a0:450d:a45a with SMTP id l15-20020a170903244f00b001a0450da45amr1742213pls.31.1678652240593; Sun, 12 Mar 2023 13:17:20 -0700 (PDT) Received: from carnotaurus.. (c-73-231-147-44.hsd1.ca.comcast.net. [73.231.147.44]) by smtp.gmail.com with ESMTPSA id t15-20020a1709028c8f00b0019aa4c00ff4sm3187594plo.206.2023.03.12.13.17.19 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 12 Mar 2023 13:17:20 -0700 (PDT) From: Joe Stringer To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, corbet@lwn.net Subject: [PATCH linux-doc] docs/doc-guide: Clarify how to write tables Date: Sun, 12 Mar 2023 13:17:12 -0700 Message-Id: <20230312201712.367545-1-joe@isovalent.com> X-Mailer: git-send-email 2.34.1 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?1760195019230884530?= X-GMAIL-MSGID: =?utf-8?q?1760195019230884530?= Prior to this commit, the kernel docs writing guide spent over a page describing exactly how *not* to write tables into the kernel docs, without providing a example about the desired format. This patch provides a positive example first in the guide so that it's harder to miss, then leaves the existing less desirable approach below for contributors to follow if they have some stronger justification for why to use that approach. Signed-off-by: Joe Stringer --- Documentation/doc-guide/sphinx.rst | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst index 23edb427e76f..9c2210b6ea3f 100644 --- a/Documentation/doc-guide/sphinx.rst +++ b/Documentation/doc-guide/sphinx.rst @@ -313,9 +313,25 @@ the documentation build system will automatically turn a reference to function name exists. If you see ``c:func:`` use in a kernel document, please feel free to remove it. +Tables +------ + +Tables should be written in cell grid form unless there is a strong +justification for using an alternate format: + +.. code-block:: rst + + +------------------------+------------+----------+----------+ + | Header row, column 1 | Header 2 | Header 3 | Header 4 | + | (header rows optional) | | | | + +========================+============+==========+==========+ + | body row 1, column 1 | column 2 | column 3 | column 4 | + +------------------------+------------+----------+----------+ + | body row 2 | ... | ... | | + +------------------------+------------+----------+----------+ list tables ------------ +~~~~~~~~~~~ The list-table formats can be useful for tables that are not easily laid out in the usual Sphinx ASCII-art formats. These formats are nearly