diff mbox series

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

Message ID 08ac283ac5bdc2664255a7ad34514e50d3ed85d8.1622898327.git.mchehab+huawei@kernel.org (mailing list archive)
State Superseded
Delegated to: Brendan Higgins
Headers show
Series docs: avoid using ReST :doc:`foo` tag | expand

Commit Message

Mauro Carvalho Chehab June 5, 2021, 1:18 p.m. UTC
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>
---
 Documentation/dev-tools/kunit/api/index.rst | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

Comments

David Gow June 5, 2021, 3:43 p.m. UTC | #1
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.)

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

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.
Mauro Carvalho Chehab June 5, 2021, 4:06 p.m. UTC | #2
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
Brendan Higgins June 7, 2021, 8:14 p.m. UTC | #3
On Sat, Jun 5, 2021 at 6:18 AM 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>

Thanks!

Acked-by: Brendan Higgins <brendanhiggins@google.com>
diff mbox series

Patch

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.