diff mbox series

[linux-doc,v3] docs/doc-guide: Clarify how to write tables

Message ID 20230424171850.3612317-1-joe@isovalent.com
State New
Headers
Series [linux-doc,v3] docs/doc-guide: Clarify how to write tables |

Commit Message

Joe Stringer April 24, 2023, 5:18 p.m. UTC 
  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>
---
v3: Fix grammar mistake
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(-)

Comments

Randy Dunlap April 24, 2023, 8:13 p.m. UTC | #1 
On 4/24/23 10:18, Joe Stringer wrote:
> 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>

Thanks.

> ---
> v3: Fix grammar mistake
> 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..cd8ad7904491 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 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
Jonathan Corbet June 9, 2023, 7:58 a.m. UTC | #2 
Joe Stringer <joe@isovalent.com> writes:

> 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>
> ---
> v3: Fix grammar mistake
> 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(-)

I stumbled across this languishing in my docs folder, sorry ... it's
applied now, thanks.

jon
diff mbox series

Patch

diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst
index 23edb427e76f..cd8ad7904491 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 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