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

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

[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.

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>
---
 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
-- 
2.34.1

Re: [PATCH linux-doc] docs/doc-guide: Clarify how to write tables

[Jonathan Corbet]

Joe Stringer <joe@isovalent.com> writes:

Thanks for working to improve the docs...I have a couple of questions,
though.

> 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.

There's all kinds of things you can do in RST, but we've deliberately
not tried to create a new RST guide in the kernel docs.  I'm not sure
that tables merit an exception to that?  If people really need help,
perhaps a link to (say)

  https://docutils.sourceforge.io/docs/user/rst/quickref.html#tables

would suffice?

> Signed-off-by: Joe Stringer <joe@isovalent.com>
> ---
>  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             | ...        | ...      |          |
> +   +------------------------+------------+----------+----------+

...and if they do merit an exception, why would we prefer the full grid
format (which is harder to create and maintain) than the simple table
format?  Most of the time, the simple format can do what's needed, and I
don't think it's less readable.

Thanks,

jon

Re: [PATCH linux-doc] docs/doc-guide: Clarify how to write tables

[Joe Stringer]

On Sun, Mar 12, 2023 at 1:24 PM Jonathan Corbet <corbet@lwn.net> wrote:
>
> Joe Stringer <joe@isovalent.com> writes:
>
> Thanks for working to improve the docs...I have a couple of questions,
> though.
>
> > 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.
>
> There's all kinds of things you can do in RST, but we've deliberately
> not tried to create a new RST guide in the kernel docs.  I'm not sure
> that tables merit an exception to that?  If people really need help,
> perhaps a link to (say)
>
>   https://docutils.sourceforge.io/docs/user/rst/quickref.html#tables
>
> would suffice?

Thanks for the review! A link with a clear recommendation would make
sense to me.

> > Signed-off-by: Joe Stringer <joe@isovalent.com>
> > ---
> >  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             | ...        | ...      |          |
> > +   +------------------------+------------+----------+----------+
>
> ...and if they do merit an exception, why would we prefer the full grid
> format (which is harder to create and maintain) than the simple table
> format?  Most of the time, the simple format can do what's needed, and I
> don't think it's less readable.

I'm not opinionated about grid format, I just picked one. But this is
interesting - If simple table is the preferred format, then that
sounds like the sort of detail that this docs page should communicate.
For example:

ReStructured text provides several formats to define tables. Kernel
style for tables is to use:
- Simple table format wherever possible
- Grid format if the table requires row spans
- Other formats if there is a specific justification (see list tables
for an example below).

See the Quick reStructured Text cheat for examples:
https://docutils.sourceforge.io/docs/user/rst/quickref.html#tables

Re: [PATCH linux-doc] docs/doc-guide: Clarify how to write tables

[Jonathan Corbet]

Joe Stringer <joe@isovalent.com> writes:

>> ...and if they do merit an exception, why would we prefer the full grid
>> format (which is harder to create and maintain) than the simple table
>> format?  Most of the time, the simple format can do what's needed, and I
>> don't think it's less readable.
>
> I'm not opinionated about grid format, I just picked one. But this is
> interesting - If simple table is the preferred format, then that
> sounds like the sort of detail that this docs page should communicate.
> For example:

I think that either format is fine, both are readable.  I just
questioned whether we should push people toward the grid format, which
takes more effort to create, in the absence of a reason to do so.

Thanks,

jon

Re: [PATCH linux-doc] docs/doc-guide: Clarify how to write tables

[Joe Stringer]

On Tue, Mar 14, 2023 at 11:14 AM Jonathan Corbet <corbet@lwn.net> wrote:
>
> Joe Stringer <joe@isovalent.com> writes:
>
> >> ...and if they do merit an exception, why would we prefer the full grid
> >> format (which is harder to create and maintain) than the simple table
> >> format?  Most of the time, the simple format can do what's needed, and I
> >> don't think it's less readable.
> >
> > I'm not opinionated about grid format, I just picked one. But this is
> > interesting - If simple table is the preferred format, then that
> > sounds like the sort of detail that this docs page should communicate.
> > For example:
>
> I think that either format is fine, both are readable.  I just
> questioned whether we should push people toward the grid format, which
> takes more effort to create, in the absence of a reason to do so.

Got it, thanks Jon. I'll spin a v2.