iv/linux
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs/doc-guide: Clarify how to write tables

Browse Source 
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 <joe@isovalent.com>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Link: https://lore.kernel.org/r/20230424171850.3612317-1-joe@isovalent.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This commit is contained in:
Joe Stringer 2023-04-24 10:18:50 -07:00 committed by Jonathan Corbet
parent eed892da9c
commit 35d4a3c67e
1 changed files with 10 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
Documentation/doc-guide/sphinx.rst
View File

@ -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 to 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