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
