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@xxxxxxx> wrote:
>
> Joe Stringer <joe@xxxxxxxxxxxxx> 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@xxxxxxxxxxxxx>
> > ---
> >  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