Em Sat, 5 Jun 2021 23:43:22 +0800
David Gow <davidgow@xxxxxxxxxx> escreveu:
> On Sat, Jun 5, 2021 at 9:18 PM Mauro Carvalho Chehab
> <mchehab+huawei@xxxxxxxxxx> 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@xxxxxxxxxx>
> > ---
>
> 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@xxxxxxxxxx>
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@xxxxxxxxxxxxxxxx.
> > 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
