Skip to contentSkip to conversation

docs/doc-guide: Clarify how to write tables

PATCH Superseded Joe Stringer 2 participants 3 messages Apr 22, 2023 – Apr 24, 2023 Documentation

v2 of 3 Superseded Latest is v3 →

lore
Share & tools
lore
#0 lore raw

PATCH v2 1/1 docs/doc-guide: Clarify how to write tables

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.

---
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(-)
Documentation/doc-guide/sphinx.rst +10 -1
index 23edb427e76f..77ac7dc27715 100644
@@ -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
Signature · 1 line
2.34.1
reviewer
#1 lore raw

Hi,

Quoted 21 lines · Joe Stringer

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.

Quoted 1 line

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.

---
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(-)
Documentation/doc-guide/sphinx.rst +0 -0
index 23edb427e76f..77ac7dc27715 100644

Documentation/doc-guide/sphinx.rst the documentation build system will automatically turn a reference to · line 320

Quoted 8 lines
Documentation/doc-guide/sphinx.rst +5 -0
@@ -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

tables is to prefer
or
tables prefers

Otherwise LGTM. It's good to have positive examples, not just negative ones.

Thanks.

Quoted 11 lines
Documentation/doc-guide/sphinx.rst +5 -1
+`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
Signature · 1 line
~Randy
#2 lore raw
Quoted 38 lines · Randy Dunlap

Hi,

Quoted 21 lines · Joe Stringer

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.

Quoted 1 line

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.

---
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(-)
Documentation/doc-guide/sphinx.rst +0 -0
index 23edb427e76f..77ac7dc27715 100644

Documentation/doc-guide/sphinx.rst the documentation build system will automatically turn a reference to · line 320

Quoted 8 lines
Documentation/doc-guide/sphinx.rst +5 -0
@@ -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

tables is to prefer
or
tables prefers

Quoted 1 line

Otherwise LGTM. It's good to have positive examples, not just negative ones.

Thanks, I'll fix this up and send a fresh version.