Re: [PATCH 02/34] docs: dev-tools: kunit: don't use a table for docs name

From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
To: David Gow <davidgow@google.com>
Cc: Jonathan Corbet <corbet@lwn.net>,
	Linux Doc Mailing List <linux-doc@vger.kernel.org>,
	Brendan Higgins <brendanhiggins@google.com>,
	KUnit Development <kunit-dev@googlegroups.com>,
	Linux Kernel Mailing List <linux-kernel@vger.kernel.org>,
	"open list:KERNEL SELFTEST FRAMEWORK" 
	<linux-kselftest@vger.kernel.org>
Subject: Re: [PATCH 02/34] docs: dev-tools: kunit: don't use a table for docs name
Date: Sat, 5 Jun 2021 18:06:41 +0200	[thread overview]
Message-ID: <20210605180641.67ed6831@coco.lan> (raw)
In-Reply-To: <CABVgOSmheB_f5gNc_zyuDHrwdRs_x_osutorJbLUMGpRRU4nzA@mail.gmail.com>

Em Sat, 5 Jun 2021 23:43:22 +0800
David Gow <davidgow@google.com> escreveu:

> On Sat, Jun 5, 2021 at 9:18 PM Mauro Carvalho Chehab
> <mchehab+huawei@kernel.org> wrote:
> >
> > We'll be replacing :doc:`foo` references to
> > Documentation/foo.rst. Yet, here it happens inside a table.
> > Doing a search-and-replace would break it.
> >
> > Yet, as there's no good reason to use a table there,
> > let's just convert it into a list.
> >
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> > ---  
> 
> While I personally quite like the look of the table when rendered by
> Sphinx, I think the list is much more readable as plain-text, so this
> is okay by me.
> 
> That being said, a definition list[1] seems like it should be better
> still, though I can't get it to work with the kernel's Sphinx
> configuration, so let's stick with this for now. (Given we've only got
> one page of documentation here, the whole thing doesn't matter much
> anyway.)

This works:

	foo
		bar

But automarkup.py currently ignores definition list syntaxes like:

	Documentation/dev-tools/kunit/api/test.rst
	  documents all of the standard testing API excluding mocking
	  or mocking related features.

Not sure why, as the regex it uses should have caught it:

    RE_doc = re.compile(r'(\bDocumentation/)?((\.\./)*[\w\-/]+)\.(rst|txt)')

Which is parsed from this loop:

    #
    # This loop could eventually be improved on.  Someday maybe we
    # want a proper tree traversal with a lot of awareness of which
    # kinds of nodes to prune.  But this works well for now.
    #
    # The nodes.literal test catches ``literal text``, its purpose is to
    # avoid adding cross-references to functions that have been explicitly
    # marked with cc:func:.
    #
    for para in doctree.traverse(nodes.paragraph):
        for node in para.traverse(nodes.Text):
            if not isinstance(node.parent, nodes.literal):
                node.parent.replace(node, markup_refs(name, app, node))

Maybe definition list is outside "nodes.Text", but I'm not a Python
expert, nor I know how Sphinx/docutils internally represents a definition 
list. 

So, the next best thing seems to be as proposed on this patch:

	Documentation/dev-tools/kunit/api/test.rst

	- documents all of the standard testing API excluding mocking
	  or mocking related features.

> Reviewed-by: David Gow <davidgow@google.com>

Thanks!
Mauro

> 
> Cheers,
> -- David
> 
> [1] https://rest-sphinx-memo.readthedocs.io/en/latest/ReST.html#definition-list
> 
> 
> >  Documentation/dev-tools/kunit/api/index.rst | 8 ++++----
> >  1 file changed, 4 insertions(+), 4 deletions(-)
> >
> > diff --git a/Documentation/dev-tools/kunit/api/index.rst b/Documentation/dev-tools/kunit/api/index.rst
> > index 9b9bffe5d41a..b33ad72bcf0b 100644
> > --- a/Documentation/dev-tools/kunit/api/index.rst
> > +++ b/Documentation/dev-tools/kunit/api/index.rst
> > @@ -10,7 +10,7 @@ API Reference
> >  This section documents the KUnit kernel testing API. It is divided into the
> >  following sections:
> >
> > -================================= ==============================================
> > -:doc:`test`                       documents all of the standard testing API
> > -                                  excluding mocking or mocking related features.
> > -================================= ==============================================
> > +Documentation/dev-tools/kunit/api/test.rst
> > +
> > + - documents all of the standard testing API excluding mocking
> > +   or mocking related features.
> > --
> > 2.31.1
> >
> > --
> > You received this message because you are subscribed to the Google Groups "KUnit Development" group.
> > To unsubscribe from this group and stop receiving emails from it, send an email to kunit-dev+unsubscribe@googlegroups.com.
> > To view this discussion on the web visit https://groups.google.com/d/msgid/kunit-dev/08ac283ac5bdc2664255a7ad34514e50d3ed85d8.1622898327.git.mchehab%2Bhuawei%40kernel.org.  

Thanks,
Mauro