From patchwork Sat Apr 22 17:52:56 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Joe Stringer X-Patchwork-Id: 86614 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a59:b0ea:0:b0:3b6:4342:cba0 with SMTP id b10csp1830527vqo; Sat, 22 Apr 2023 10:58:25 -0700 (PDT) X-Google-Smtp-Source: AKy350bwehHSN+W5VIBaUQKG7gZ3tUOTtgF3H6NZ17OErnHWQV/4h00uC1abA3aVkZgFGu2vW+Qk X-Received: by 2002:a17:902:d2d2:b0:1a6:9d98:e763 with SMTP id n18-20020a170902d2d200b001a69d98e763mr12299187plc.26.1682186305683; Sat, 22 Apr 2023 10:58:25 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1682186305; cv=none; d=google.com; s=arc-20160816; b=VzzNK7VHHa/hg6ug4VYsnXqPiTF4lHr0MyOQNM4zQVX0K9r6Fmxxxi2lrzB5VqcuKO vgm7VlaHnqLwsPlmTZOXXdOUPq5s1GGxoXfsWMLx2wrkIhWF34bfASlDczvkKskeypXF R/kYauWx5wfV0GAn2p1iHuZXVJ7yr1b0W8+WSuTutDr/kGw38vEz7SU4InhoespO9Qda 9Km97O+xX+6WAcg3rgrs3pUPhr2/H6unrMM8FuWQ1FBohk8GXsYpchrIMLyrGKIqCXvo itD4lJ6N96zHxC96RU9/hOZMFG29JZbnxLNLjDk6DJyVBwIPRbfz81p3WnHDfX9A7m2v 7rIA== 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=cUwLHex7C0qMDCMBJbcjdVcJIndC8iDzP/c9aUCV0NQ=; b=sgASUB2ibo+KQuK1Y6uGdmMiuKa4cNYj0cAnEGGbSvDPqs+ReXDOUCcbmD/1lG2sVh feI5MkaKJmDAEoKC18RoEqIgjke/F2e6fb8XGQhxIns/hZuVnuswikUwnrzU70uAftcH h16dqdp2aHIsGh9w8/vqxn9QYmbUg61XZ94svcqBRxQqvP06+l38A0960T/v4n2bBp1P Hd199wqIMTeyZG4CAGzTePR4JCgScjSM6JXi+s/oShlXU2SC3Nd2lhfadmJTmizdurhP KEmpi8yk4LvtNnMVjIqQ0VPb9W9ESvrnYotRUqz6HL5+0DH8tm0CiJx7MZTrBvo6Ez9V +tCQ== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@isovalent.com header.s=google header.b=GZb5EdcE; 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 u6-20020a17090341c600b001a52a50e167si8374417ple.573.2023.04.22.10.58.11; Sat, 22 Apr 2023 10:58:25 -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=GZb5EdcE; 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 S229556AbjDVRxF (ORCPT + 99 others); Sat, 22 Apr 2023 13:53:05 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:42928 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229508AbjDVRxC (ORCPT ); Sat, 22 Apr 2023 13:53:02 -0400 Received: from mail-pl1-x62b.google.com (mail-pl1-x62b.google.com [IPv6:2607:f8b0:4864:20::62b]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id D992F1FEB for ; Sat, 22 Apr 2023 10:53:00 -0700 (PDT) Received: by mail-pl1-x62b.google.com with SMTP id d9443c01a7336-1a5197f00e9so26743655ad.1 for ; Sat, 22 Apr 2023 10:53:00 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=isovalent.com; s=google; t=1682185980; x=1684777980; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:from:to:cc:subject:date:message-id:reply-to; bh=cUwLHex7C0qMDCMBJbcjdVcJIndC8iDzP/c9aUCV0NQ=; b=GZb5EdcEM1+UWMyalZaRnvlyIxe2QKWw+ojKu9jtqu6Ow/xPh64SMPcszyFyQz+SYV ynk8iN2tycPtYEpVkftN+E1hI4Q5E/1lHejnkl5pb4jTTC+jRdqftSnO92qF07i5Q7lN 0M3bH70bnyfiWF+YRlF47c3aSvD++76u095DdJaxzF7C6I2KG9FH2bRJ7r7zxCQTuV6k R56cUhSjY6ku6UV2ucGINPbkbAWGySB/Jec0SaSYTHiqyYv3F1FchQ+3t/oxKF5ReutV Zf5pu5ithdijJbD7DxJx3CuYfMX+QTS8+TBMAjDAfMpeR/UgpxF/3JH2Sji44BsmkkAU E9hw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1682185980; x=1684777980; 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=cUwLHex7C0qMDCMBJbcjdVcJIndC8iDzP/c9aUCV0NQ=; b=acQDCoKbwozjcvMyGgHOrKvAIalcsqfD8L/rHIhbBx/ZQNVE0jd2YJ4Rf91IE1DvJW kDfsy/rBUWuEvqvKku8nyxztyGIGg7RRWjlrAZ4d4gUzR28pabz9e3JjbxclU7QlEdl3 aPxEuWe+Aalyp1Ccquf25Gch0EEvSS8fDhLpKfuhiyPDGE498nKpU4QFxr0hNcfNIgjK 9mCD1bly09Uf+NaJhFd+AK0Pw/U14RqLAdBWUqaivFKsHLFD//fui76qCaEs1mezwcQ/ GD1xT8dnL1XAWkJAj+nXztyfAhBIpNkYjkrSHczk3n79TDdia3zNs9zwZfCzhHYmzSm9 H6gA== X-Gm-Message-State: AAQBX9dKyO2MmJR55cW8JgXYyqicHuvXgac4KAwUeJ8OTui11zxi9ZUF nJIyFKq0UfSUWZFY7ZwB/VCzxWHLHrbOQK62UY+t3w== X-Received: by 2002:a17:902:d503:b0:1a9:6d12:9f29 with SMTP id b3-20020a170902d50300b001a96d129f29mr150133plg.36.1682185980130; Sat, 22 Apr 2023 10:53:00 -0700 (PDT) Received: from carnotaurus.. (c-73-252-184-87.hsd1.ca.comcast.net. [73.252.184.87]) by smtp.gmail.com with ESMTPSA id y11-20020a170902864b00b0019c2b1c4db1sm4247513plt.239.2023.04.22.10.52.59 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sat, 22 Apr 2023 10:52:59 -0700 (PDT) From: Joe Stringer To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, corbet@lwn.net Subject: [PATCH linux-doc v2] docs/doc-guide: Clarify how to write tables Date: Sat, 22 Apr 2023 10:52:56 -0700 Message-Id: <20230422175256.3396430-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,T_SCC_BODY_TEXT_LINE,URIBL_BLOCKED autolearn=unavailable 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?1763900187887906020?= X-GMAIL-MSGID: =?utf-8?q?1763900187887906020?= 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 --- v2: Simplify recommendation for either simple or grid table syntax Remove example, link to rST user reference --- Documentation/doc-guide/sphinx.rst | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst index 23edb427e76f..77ac7dc27715 100644 --- a/Documentation/doc-guide/sphinx.rst +++ b/Documentation/doc-guide/sphinx.rst @@ -313,9 +313,18 @@ 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 +------ + +ReStructuredText provides several options for table syntax. Kernel style for +tables is prefer *simple table* syntax or *grid table* syntax. See the +`reStructuredText user reference for table syntax`_ for more details. + +.. _reStructuredText user reference for table syntax: + https://docutils.sourceforge.io/docs/user/rst/quickref.html#tables 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