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@xxxxxxxxxxxxx> Reviewed-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx> 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 -- ~Randy
