* [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag @ 2021-06-05 13:17 Mauro Carvalho Chehab 2021-06-05 13:18 ` [PATCH 02/34] docs: dev-tools: kunit: don't use a table for docs name Mauro Carvalho Chehab ` (3 more replies) 0 siblings, 4 replies; 17+ messages in thread From: Mauro Carvalho Chehab @ 2021-06-05 13:17 UTC (permalink / raw) To: Jonathan Corbet, Linux Doc Mailing List Cc: Mauro Carvalho Chehab, linux-kernel, bpf, coresight, devicetree, kunit-dev, kvm, linux-acpi, linux-arm-kernel, linux-gpio, linux-hwmon, linux-i2c, linux-kselftest, linux-media, linux-pci, linux-pm, linux-security-module, netdev As discussed at: https://lore.kernel.org/linux-doc/871r9k6rmy.fsf@meer.lwn.net/ It is better to avoid using :doc:`foo` to refer to Documentation/foo.rst, as the automarkup.py extension should handle it automatically, on most cases. There are a couple of exceptions to this rule: 1. when :doc: tag is used to point to a kernel-doc DOC: markup; 2. when it is used with a named tag, e. g. :doc:`some name <foo>`; It should also be noticed that automarkup.py has currently an issue: if one use a markup like: Documentation/dev-tools/kunit/api/test.rst - documents all of the standard testing API excluding mocking or mocking related features. or, even: Documentation/dev-tools/kunit/api/test.rst documents all of the standard testing API excluding mocking or mocking related features. The automarkup.py will simply ignore it. Not sure why. This patch series avoid the above patterns (which is present only on 4 files), but it would be nice to have a followup patch fixing the issue at automarkup.py. On this series: Patch 1 manually adjust the references inside driver-api/pm/devices.rst, as there it uses :file:`foo` to refer to some Documentation/ files; Patch 2 converts a table at Documentation/dev-tools/kunit/api/index.rst into a list, carefully avoiding the Patch 3 converts the cross-references at the media documentation, also avoiding the automarkup.py bug; Patches 4-34 convert the other occurrences via a replace script. They were manually edited, in order to honour 80-columns where possible. I did a diff between the Sphinx 2.4.4 output before and after this patch series in order to double-check that all converted Documentation/ references will produce <a href=<foo>.rst>foo title</a> tags. Mauro Carvalho Chehab (34): docs: devices.rst: better reference documentation docs docs: dev-tools: kunit: don't use a table for docs name media: docs: */media/index.rst: don't use ReST doc:`foo` media: userspace-api: avoid using ReST :doc:`foo` markup media: driver-api: drivers: avoid using ReST :doc:`foo` markup media: admin-guide: avoid using ReST :doc:`foo` markup docs: admin-guide: pm: avoid using ReSt :doc:`foo` markup docs: admin-guide: hw-vuln: avoid using ReST :doc:`foo` markup docs: admin-guide: sysctl: avoid using ReST :doc:`foo` markup docs: block: biodoc.rst: avoid using ReSt :doc:`foo` markup docs: bpf: bpf_lsm.rst: avoid using ReSt :doc:`foo` markup docs: core-api: avoid using ReSt :doc:`foo` markup docs: dev-tools: testing-overview.rst: avoid using ReSt :doc:`foo` markup docs: dev-tools: kunit: avoid using ReST :doc:`foo` markup docs: devicetree: bindings: submitting-patches.rst: avoid using ReSt :doc:`foo` markup docs: doc-guide: avoid using ReSt :doc:`foo` markup docs: driver-api: avoid using ReSt :doc:`foo` markup docs: driver-api: gpio: using-gpio.rst: avoid using ReSt :doc:`foo` markup docs: driver-api: surface_aggregator: avoid using ReSt :doc:`foo` markup docs: driver-api: usb: avoid using ReSt :doc:`foo` markup docs: firmware-guide: acpi: avoid using ReSt :doc:`foo` markup docs: hwmon: adm1177.rst: avoid using ReSt :doc:`foo` markup docs: i2c: avoid using ReSt :doc:`foo` markup docs: kernel-hacking: hacking.rst: avoid using ReSt :doc:`foo` markup docs: networking: devlink: avoid using ReSt :doc:`foo` markup docs: PCI: endpoint: pci-endpoint-cfs.rst: avoid using ReSt :doc:`foo` markup docs: PCI: pci.rst: avoid using ReSt :doc:`foo` markup docs: process: submitting-patches.rst: avoid using ReSt :doc:`foo` markup docs: security: landlock.rst: avoid using ReSt :doc:`foo` markup docs: trace: coresight: coresight.rst: avoid using ReSt :doc:`foo` markup docs: trace: ftrace.rst: avoid using ReSt :doc:`foo` markup docs: userspace-api: landlock.rst: avoid using ReSt :doc:`foo` markup docs: virt: kvm: s390-pv-boot.rst: avoid using ReSt :doc:`foo` markup docs: x86: avoid using ReSt :doc:`foo` markup .../PCI/endpoint/pci-endpoint-cfs.rst | 2 +- Documentation/PCI/pci.rst | 6 +-- .../special-register-buffer-data-sampling.rst | 3 +- Documentation/admin-guide/media/bt8xx.rst | 15 ++++---- Documentation/admin-guide/media/bttv.rst | 21 ++++++----- Documentation/admin-guide/media/index.rst | 12 +++--- Documentation/admin-guide/media/saa7134.rst | 3 +- Documentation/admin-guide/pm/intel_idle.rst | 16 +++++--- Documentation/admin-guide/pm/intel_pstate.rst | 9 +++-- Documentation/admin-guide/sysctl/abi.rst | 2 +- Documentation/admin-guide/sysctl/kernel.rst | 37 ++++++++++--------- Documentation/block/biodoc.rst | 2 +- Documentation/bpf/bpf_lsm.rst | 13 ++++--- .../core-api/bus-virt-phys-mapping.rst | 2 +- Documentation/core-api/dma-api.rst | 5 ++- Documentation/core-api/dma-isa-lpc.rst | 2 +- Documentation/core-api/index.rst | 4 +- Documentation/dev-tools/kunit/api/index.rst | 8 ++-- Documentation/dev-tools/kunit/faq.rst | 2 +- Documentation/dev-tools/kunit/index.rst | 14 +++---- Documentation/dev-tools/kunit/start.rst | 6 +-- Documentation/dev-tools/kunit/tips.rst | 5 ++- Documentation/dev-tools/kunit/usage.rst | 8 ++-- Documentation/dev-tools/testing-overview.rst | 16 ++++---- .../bindings/submitting-patches.rst | 11 +++--- Documentation/doc-guide/contributing.rst | 8 ++-- Documentation/driver-api/gpio/using-gpio.rst | 4 +- Documentation/driver-api/ioctl.rst | 2 +- .../driver-api/media/drivers/bttv-devel.rst | 2 +- Documentation/driver-api/media/index.rst | 10 +++-- Documentation/driver-api/pm/devices.rst | 8 ++-- .../surface_aggregator/clients/index.rst | 3 +- .../surface_aggregator/internal.rst | 15 ++++---- .../surface_aggregator/overview.rst | 6 ++- Documentation/driver-api/usb/dma.rst | 6 +-- .../acpi/dsd/data-node-references.rst | 3 +- .../firmware-guide/acpi/dsd/graph.rst | 2 +- .../firmware-guide/acpi/enumeration.rst | 7 ++-- Documentation/hwmon/adm1177.rst | 3 +- Documentation/i2c/instantiating-devices.rst | 2 +- Documentation/i2c/old-module-parameters.rst | 3 +- Documentation/i2c/smbus-protocol.rst | 4 +- Documentation/kernel-hacking/hacking.rst | 4 +- .../networking/devlink/devlink-region.rst | 2 +- .../networking/devlink/devlink-trap.rst | 4 +- Documentation/process/submitting-patches.rst | 32 ++++++++-------- Documentation/security/landlock.rst | 3 +- Documentation/trace/coresight/coresight.rst | 8 ++-- Documentation/trace/ftrace.rst | 2 +- Documentation/userspace-api/landlock.rst | 11 +++--- .../userspace-api/media/glossary.rst | 2 +- Documentation/userspace-api/media/index.rst | 12 +++--- Documentation/virt/kvm/s390-pv-boot.rst | 2 +- Documentation/x86/boot.rst | 4 +- Documentation/x86/mtrr.rst | 2 +- 55 files changed, 217 insertions(+), 183 deletions(-) -- 2.31.1 ^ permalink raw reply [flat|nested] 17+ messages in thread
* [PATCH 02/34] docs: dev-tools: kunit: don't use a table for docs name 2021-06-05 13:17 [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag Mauro Carvalho Chehab @ 2021-06-05 13:18 ` Mauro Carvalho Chehab 2021-06-05 15:43 ` David Gow 2021-06-07 20:14 ` Brendan Higgins 2021-06-05 13:18 ` [PATCH 14/34] docs: dev-tools: kunit: avoid using ReST :doc:`foo` markup Mauro Carvalho Chehab ` (2 subsequent siblings) 3 siblings, 2 replies; 17+ messages in thread From: Mauro Carvalho Chehab @ 2021-06-05 13:18 UTC (permalink / raw) To: Jonathan Corbet, Linux Doc Mailing List Cc: Mauro Carvalho Chehab, Brendan Higgins, kunit-dev, linux-kernel, linux-kselftest 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(-) 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 ^ permalink raw reply related [flat|nested] 17+ messages in thread
* Re: [PATCH 02/34] docs: dev-tools: kunit: don't use a table for docs name 2021-06-05 13:18 ` [PATCH 02/34] docs: dev-tools: kunit: don't use a table for docs name Mauro Carvalho Chehab @ 2021-06-05 15:43 ` David Gow 2021-06-05 16:06 ` Mauro Carvalho Chehab 2021-06-07 20:14 ` Brendan Higgins 1 sibling, 1 reply; 17+ messages in thread From: David Gow @ 2021-06-05 15:43 UTC (permalink / raw) To: Mauro Carvalho Chehab Cc: Jonathan Corbet, Linux Doc Mailing List, Brendan Higgins, KUnit Development, Linux Kernel Mailing List, open list:KERNEL SELFTEST FRAMEWORK 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. ^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [PATCH 02/34] docs: dev-tools: kunit: don't use a table for docs name 2021-06-05 15:43 ` David Gow @ 2021-06-05 16:06 ` Mauro Carvalho Chehab 0 siblings, 0 replies; 17+ messages in thread From: Mauro Carvalho Chehab @ 2021-06-05 16:06 UTC (permalink / raw) To: David Gow Cc: Jonathan Corbet, Linux Doc Mailing List, Brendan Higgins, KUnit Development, Linux Kernel Mailing List, open list:KERNEL SELFTEST FRAMEWORK 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 ^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [PATCH 02/34] docs: dev-tools: kunit: don't use a table for docs name 2021-06-05 13:18 ` [PATCH 02/34] docs: dev-tools: kunit: don't use a table for docs name Mauro Carvalho Chehab 2021-06-05 15:43 ` David Gow @ 2021-06-07 20:14 ` Brendan Higgins 1 sibling, 0 replies; 17+ messages in thread From: Brendan Higgins @ 2021-06-07 20:14 UTC (permalink / raw) To: Mauro Carvalho Chehab Cc: Jonathan Corbet, Linux Doc Mailing List, KUnit Development, Linux Kernel Mailing List, open list:KERNEL SELFTEST FRAMEWORK 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> ^ permalink raw reply [flat|nested] 17+ messages in thread
* [PATCH 14/34] docs: dev-tools: kunit: avoid using ReST :doc:`foo` markup 2021-06-05 13:17 [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag Mauro Carvalho Chehab 2021-06-05 13:18 ` [PATCH 02/34] docs: dev-tools: kunit: don't use a table for docs name Mauro Carvalho Chehab @ 2021-06-05 13:18 ` Mauro Carvalho Chehab 2021-06-05 15:44 ` David Gow 2021-06-07 20:20 ` Brendan Higgins 2021-06-05 13:37 ` [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag Mauro Carvalho Chehab 2021-06-05 15:11 ` Nícolas F. R. A. Prado 3 siblings, 2 replies; 17+ messages in thread From: Mauro Carvalho Chehab @ 2021-06-05 13:18 UTC (permalink / raw) To: Jonathan Corbet, Linux Doc Mailing List Cc: Mauro Carvalho Chehab, Brendan Higgins, kunit-dev, linux-kernel, linux-kselftest The :doc:`foo` tag is auto-generated via automarkup.py. So, use the filename at the sources, instead of :doc:`foo`. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> --- Documentation/dev-tools/kunit/faq.rst | 2 +- Documentation/dev-tools/kunit/index.rst | 14 +++++++------- Documentation/dev-tools/kunit/start.rst | 6 +++--- Documentation/dev-tools/kunit/tips.rst | 5 +++-- Documentation/dev-tools/kunit/usage.rst | 8 +++++--- 5 files changed, 19 insertions(+), 16 deletions(-) diff --git a/Documentation/dev-tools/kunit/faq.rst b/Documentation/dev-tools/kunit/faq.rst index 8d5029ad210a..5c6555d020f3 100644 --- a/Documentation/dev-tools/kunit/faq.rst +++ b/Documentation/dev-tools/kunit/faq.rst @@ -97,7 +97,7 @@ things to try. modules will automatically execute associated tests when loaded. Test results can be collected from ``/sys/kernel/debug/kunit/<test suite>/results``, and can be parsed with ``kunit.py parse``. For more details, see "KUnit on - non-UML architectures" in :doc:`usage`. + non-UML architectures" in Documentation/dev-tools/kunit/usage.rst. If none of the above tricks help, you are always welcome to email any issues to kunit-dev@googlegroups.com. diff --git a/Documentation/dev-tools/kunit/index.rst b/Documentation/dev-tools/kunit/index.rst index 848478838347..25d92a9a05ea 100644 --- a/Documentation/dev-tools/kunit/index.rst +++ b/Documentation/dev-tools/kunit/index.rst @@ -36,7 +36,7 @@ To make running these tests (and reading the results) easier, KUnit offers results. This provides a quick way of running KUnit tests during development, without requiring a virtual machine or separate hardware. -Get started now: :doc:`start` +Get started now: Documentation/dev-tools/kunit/start.rst Why KUnit? ========== @@ -88,9 +88,9 @@ it takes to read their test log? How do I use it? ================ -* :doc:`start` - for new users of KUnit -* :doc:`tips` - for short examples of best practices -* :doc:`usage` - for a more detailed explanation of KUnit features -* :doc:`api/index` - for the list of KUnit APIs used for testing -* :doc:`kunit-tool` - for more information on the kunit_tool helper script -* :doc:`faq` - for answers to some common questions about KUnit +* Documentation/dev-tools/kunit/start.rst - for new users of KUnit +* Documentation/dev-tools/kunit/tips.rst - for short examples of best practices +* Documentation/dev-tools/kunit/usage.rst - for a more detailed explanation of KUnit features +* Documentation/dev-tools/kunit/api/index.rst - for the list of KUnit APIs used for testing +* Documentation/dev-tools/kunit/kunit-tool.rst - for more information on the kunit_tool helper script +* Documentation/dev-tools/kunit/faq.rst - for answers to some common questions about KUnit diff --git a/Documentation/dev-tools/kunit/start.rst b/Documentation/dev-tools/kunit/start.rst index 0e65cabe08eb..ee21e482a0de 100644 --- a/Documentation/dev-tools/kunit/start.rst +++ b/Documentation/dev-tools/kunit/start.rst @@ -21,7 +21,7 @@ The wrapper can be run with: ./tools/testing/kunit/kunit.py run For more information on this wrapper (also called kunit_tool) check out the -:doc:`kunit-tool` page. +Documentation/dev-tools/kunit/kunit-tool.rst page. Creating a .kunitconfig ----------------------- @@ -234,7 +234,7 @@ Congrats! You just wrote your first KUnit test! Next Steps ========== -* Check out the :doc:`tips` page for tips on +* Check out the Documentation/dev-tools/kunit/tips.rst page for tips on writing idiomatic KUnit tests. -* Optional: see the :doc:`usage` page for a more +* Optional: see the Documentation/dev-tools/kunit/usage.rst page for a more in-depth explanation of KUnit. diff --git a/Documentation/dev-tools/kunit/tips.rst b/Documentation/dev-tools/kunit/tips.rst index 8d8c238f7f79..492d2ded2f5a 100644 --- a/Documentation/dev-tools/kunit/tips.rst +++ b/Documentation/dev-tools/kunit/tips.rst @@ -125,7 +125,8 @@ Here's a slightly in-depth example of how one could implement "mocking": Note: here we're able to get away with using ``test->priv``, but if you wanted -something more flexible you could use a named ``kunit_resource``, see :doc:`api/test`. +something more flexible you could use a named ``kunit_resource``, see +Documentation/dev-tools/kunit/api/test.rst. Failing the current test ------------------------ @@ -185,5 +186,5 @@ Alternatively, one can take full control over the error message by using ``KUNIT Next Steps ========== -* Optional: see the :doc:`usage` page for a more +* Optional: see the Documentation/dev-tools/kunit/usage.rst page for a more in-depth explanation of KUnit. diff --git a/Documentation/dev-tools/kunit/usage.rst b/Documentation/dev-tools/kunit/usage.rst index 650f99590df5..3ee7ab91f712 100644 --- a/Documentation/dev-tools/kunit/usage.rst +++ b/Documentation/dev-tools/kunit/usage.rst @@ -10,7 +10,7 @@ understand it. This guide assumes a working knowledge of the Linux kernel and some basic knowledge of testing. For a high level introduction to KUnit, including setting up KUnit for your -project, see :doc:`start`. +project, see Documentation/dev-tools/kunit/start.rst. Organization of this document ============================= @@ -99,7 +99,8 @@ violated; however, the test will continue running, potentially trying other expectations until the test case ends or is otherwise terminated. This is as opposed to *assertions* which are discussed later. -To learn about more expectations supported by KUnit, see :doc:`api/test`. +To learn about more expectations supported by KUnit, see +Documentation/dev-tools/kunit/api/test.rst. .. note:: A single test case should be pretty short, pretty easy to understand, @@ -216,7 +217,8 @@ test suite in a special linker section so that it can be run by KUnit either after late_init, or when the test module is loaded (depending on whether the test was built in or not). -For more information on these types of things see the :doc:`api/test`. +For more information on these types of things see the +Documentation/dev-tools/kunit/api/test.rst. Common Patterns =============== -- 2.31.1 ^ permalink raw reply related [flat|nested] 17+ messages in thread
* Re: [PATCH 14/34] docs: dev-tools: kunit: avoid using ReST :doc:`foo` markup 2021-06-05 13:18 ` [PATCH 14/34] docs: dev-tools: kunit: avoid using ReST :doc:`foo` markup Mauro Carvalho Chehab @ 2021-06-05 15:44 ` David Gow 2021-06-16 6:00 ` Mauro Carvalho Chehab 2021-06-07 20:20 ` Brendan Higgins 1 sibling, 1 reply; 17+ messages in thread From: David Gow @ 2021-06-05 15:44 UTC (permalink / raw) To: Mauro Carvalho Chehab Cc: Jonathan Corbet, Linux Doc Mailing List, Brendan Higgins, KUnit Development, Linux Kernel Mailing List, open list:KERNEL SELFTEST FRAMEWORK On Sat, Jun 5, 2021 at 9:18 PM Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote: > > The :doc:`foo` tag is auto-generated via automarkup.py. > So, use the filename at the sources, instead of :doc:`foo`. > > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> > --- This is much better, thanks! Do note that there's a merge conflict (and another :doc:`` tag which needs updating) in the kunit-fixes branch: https://git.kernel.org/pub/scm/linux/kernel/git/shuah/linux-kselftest.git/commit/?h=kunit-fixes&id=11dbc62a73a7da9f3697e8ce83d07503c11dcabb Reviewed-by: David Gow <davidgow@google.com> Cheers, -- David > Documentation/dev-tools/kunit/faq.rst | 2 +- > Documentation/dev-tools/kunit/index.rst | 14 +++++++------- > Documentation/dev-tools/kunit/start.rst | 6 +++--- > Documentation/dev-tools/kunit/tips.rst | 5 +++-- > Documentation/dev-tools/kunit/usage.rst | 8 +++++--- > 5 files changed, 19 insertions(+), 16 deletions(-) > > diff --git a/Documentation/dev-tools/kunit/faq.rst b/Documentation/dev-tools/kunit/faq.rst > index 8d5029ad210a..5c6555d020f3 100644 > --- a/Documentation/dev-tools/kunit/faq.rst > +++ b/Documentation/dev-tools/kunit/faq.rst > @@ -97,7 +97,7 @@ things to try. > modules will automatically execute associated tests when loaded. Test results > can be collected from ``/sys/kernel/debug/kunit/<test suite>/results``, and > can be parsed with ``kunit.py parse``. For more details, see "KUnit on > - non-UML architectures" in :doc:`usage`. > + non-UML architectures" in Documentation/dev-tools/kunit/usage.rst. > > If none of the above tricks help, you are always welcome to email any issues to > kunit-dev@googlegroups.com. > diff --git a/Documentation/dev-tools/kunit/index.rst b/Documentation/dev-tools/kunit/index.rst > index 848478838347..25d92a9a05ea 100644 > --- a/Documentation/dev-tools/kunit/index.rst > +++ b/Documentation/dev-tools/kunit/index.rst > @@ -36,7 +36,7 @@ To make running these tests (and reading the results) easier, KUnit offers > results. This provides a quick way of running KUnit tests during development, > without requiring a virtual machine or separate hardware. > > -Get started now: :doc:`start` > +Get started now: Documentation/dev-tools/kunit/start.rst > > Why KUnit? > ========== > @@ -88,9 +88,9 @@ it takes to read their test log? > How do I use it? > ================ > > -* :doc:`start` - for new users of KUnit > -* :doc:`tips` - for short examples of best practices > -* :doc:`usage` - for a more detailed explanation of KUnit features > -* :doc:`api/index` - for the list of KUnit APIs used for testing > -* :doc:`kunit-tool` - for more information on the kunit_tool helper script > -* :doc:`faq` - for answers to some common questions about KUnit > +* Documentation/dev-tools/kunit/start.rst - for new users of KUnit > +* Documentation/dev-tools/kunit/tips.rst - for short examples of best practices > +* Documentation/dev-tools/kunit/usage.rst - for a more detailed explanation of KUnit features > +* Documentation/dev-tools/kunit/api/index.rst - for the list of KUnit APIs used for testing > +* Documentation/dev-tools/kunit/kunit-tool.rst - for more information on the kunit_tool helper script > +* Documentation/dev-tools/kunit/faq.rst - for answers to some common questions about KUnit > diff --git a/Documentation/dev-tools/kunit/start.rst b/Documentation/dev-tools/kunit/start.rst > index 0e65cabe08eb..ee21e482a0de 100644 > --- a/Documentation/dev-tools/kunit/start.rst > +++ b/Documentation/dev-tools/kunit/start.rst > @@ -21,7 +21,7 @@ The wrapper can be run with: > ./tools/testing/kunit/kunit.py run > > For more information on this wrapper (also called kunit_tool) check out the > -:doc:`kunit-tool` page. > +Documentation/dev-tools/kunit/kunit-tool.rst page. > > Creating a .kunitconfig > ----------------------- > @@ -234,7 +234,7 @@ Congrats! You just wrote your first KUnit test! > > Next Steps > ========== > -* Check out the :doc:`tips` page for tips on > +* Check out the Documentation/dev-tools/kunit/tips.rst page for tips on > writing idiomatic KUnit tests. > -* Optional: see the :doc:`usage` page for a more > +* Optional: see the Documentation/dev-tools/kunit/usage.rst page for a more > in-depth explanation of KUnit. > diff --git a/Documentation/dev-tools/kunit/tips.rst b/Documentation/dev-tools/kunit/tips.rst > index 8d8c238f7f79..492d2ded2f5a 100644 > --- a/Documentation/dev-tools/kunit/tips.rst > +++ b/Documentation/dev-tools/kunit/tips.rst > @@ -125,7 +125,8 @@ Here's a slightly in-depth example of how one could implement "mocking": > > > Note: here we're able to get away with using ``test->priv``, but if you wanted > -something more flexible you could use a named ``kunit_resource``, see :doc:`api/test`. > +something more flexible you could use a named ``kunit_resource``, see > +Documentation/dev-tools/kunit/api/test.rst. > > Failing the current test > ------------------------ > @@ -185,5 +186,5 @@ Alternatively, one can take full control over the error message by using ``KUNIT > > Next Steps > ========== > -* Optional: see the :doc:`usage` page for a more > +* Optional: see the Documentation/dev-tools/kunit/usage.rst page for a more > in-depth explanation of KUnit. > diff --git a/Documentation/dev-tools/kunit/usage.rst b/Documentation/dev-tools/kunit/usage.rst > index 650f99590df5..3ee7ab91f712 100644 > --- a/Documentation/dev-tools/kunit/usage.rst > +++ b/Documentation/dev-tools/kunit/usage.rst > @@ -10,7 +10,7 @@ understand it. This guide assumes a working knowledge of the Linux kernel and > some basic knowledge of testing. > > For a high level introduction to KUnit, including setting up KUnit for your > -project, see :doc:`start`. > +project, see Documentation/dev-tools/kunit/start.rst. > > Organization of this document > ============================= > @@ -99,7 +99,8 @@ violated; however, the test will continue running, potentially trying other > expectations until the test case ends or is otherwise terminated. This is as > opposed to *assertions* which are discussed later. > > -To learn about more expectations supported by KUnit, see :doc:`api/test`. > +To learn about more expectations supported by KUnit, see > +Documentation/dev-tools/kunit/api/test.rst. > > .. note:: > A single test case should be pretty short, pretty easy to understand, > @@ -216,7 +217,8 @@ test suite in a special linker section so that it can be run by KUnit either > after late_init, or when the test module is loaded (depending on whether the > test was built in or not). > > -For more information on these types of things see the :doc:`api/test`. > +For more information on these types of things see the > +Documentation/dev-tools/kunit/api/test.rst. > > Common Patterns > =============== > -- > 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/a3ad84108a5b254e545f88e58d411f5fe2e25c7e.1622898327.git.mchehab%2Bhuawei%40kernel.org. ^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [PATCH 14/34] docs: dev-tools: kunit: avoid using ReST :doc:`foo` markup 2021-06-05 15:44 ` David Gow @ 2021-06-16 6:00 ` Mauro Carvalho Chehab 2021-06-16 6:13 ` Mauro Carvalho Chehab 0 siblings, 1 reply; 17+ messages in thread From: Mauro Carvalho Chehab @ 2021-06-16 6:00 UTC (permalink / raw) To: David Gow Cc: Jonathan Corbet, Linux Doc Mailing List, Brendan Higgins, KUnit Development, Linux Kernel Mailing List, open list:KERNEL SELFTEST FRAMEWORK Em Sat, 5 Jun 2021 23:44:41 +0800 David Gow <davidgow@google.com> escreveu: > On Sat, Jun 5, 2021 at 9:18 PM Mauro Carvalho Chehab > <mchehab+huawei@kernel.org> wrote: > > > > The :doc:`foo` tag is auto-generated via automarkup.py. > > So, use the filename at the sources, instead of :doc:`foo`. > > > > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> > > --- > > This is much better, thanks! Do note that there's a merge conflict > (and another :doc:`` tag which needs updating) in the kunit-fixes > branch: > https://git.kernel.org/pub/scm/linux/kernel/git/shuah/linux-kselftest.git/commit/?h=kunit-fixes&id=11dbc62a73a7da9f3697e8ce83d07503c11dcabb Ok, thanks for the warning. I'm folding the enclosed patch: <patch> diff --git a/Documentation/dev-tools/kunit/faq.rst b/Documentation/dev-tools/kunit/faq.rst index 8d5029ad210a..5c6555d020f3 100644 --- a/Documentation/dev-tools/kunit/faq.rst +++ b/Documentation/dev-tools/kunit/faq.rst @@ -97,7 +97,7 @@ things to try. modules will automatically execute associated tests when loaded. Test results can be collected from ``/sys/kernel/debug/kunit/<test suite>/results``, and can be parsed with ``kunit.py parse``. For more details, see "KUnit on - non-UML architectures" in :doc:`usage`. + non-UML architectures" in Documentation/dev-tools/kunit/usage.rst. If none of the above tricks help, you are always welcome to email any issues to kunit-dev@googlegroups.com. diff --git a/Documentation/dev-tools/kunit/index.rst b/Documentation/dev-tools/kunit/index.rst index 848478838347..25d92a9a05ea 100644 --- a/Documentation/dev-tools/kunit/index.rst +++ b/Documentation/dev-tools/kunit/index.rst @@ -36,7 +36,7 @@ To make running these tests (and reading the results) easier, KUnit offers results. This provides a quick way of running KUnit tests during development, without requiring a virtual machine or separate hardware. -Get started now: :doc:`start` +Get started now: Documentation/dev-tools/kunit/start.rst Why KUnit? ========== @@ -88,9 +88,9 @@ it takes to read their test log? How do I use it? ================ -* :doc:`start` - for new users of KUnit -* :doc:`tips` - for short examples of best practices -* :doc:`usage` - for a more detailed explanation of KUnit features -* :doc:`api/index` - for the list of KUnit APIs used for testing -* :doc:`kunit-tool` - for more information on the kunit_tool helper script -* :doc:`faq` - for answers to some common questions about KUnit +* Documentation/dev-tools/kunit/start.rst - for new users of KUnit +* Documentation/dev-tools/kunit/tips.rst - for short examples of best practices +* Documentation/dev-tools/kunit/usage.rst - for a more detailed explanation of KUnit features +* Documentation/dev-tools/kunit/api/index.rst - for the list of KUnit APIs used for testing +* Documentation/dev-tools/kunit/kunit-tool.rst - for more information on the kunit_tool helper script +* Documentation/dev-tools/kunit/faq.rst - for answers to some common questions about KUnit diff --git a/Documentation/dev-tools/kunit/start.rst b/Documentation/dev-tools/kunit/start.rst index 0e65cabe08eb..63ef7b625c13 100644 --- a/Documentation/dev-tools/kunit/start.rst +++ b/Documentation/dev-tools/kunit/start.rst @@ -21,7 +21,7 @@ The wrapper can be run with: ./tools/testing/kunit/kunit.py run For more information on this wrapper (also called kunit_tool) check out the -:doc:`kunit-tool` page. +Documentation/dev-tools/kunit/kunit-tool.rst page. Creating a .kunitconfig ----------------------- @@ -234,7 +234,7 @@ Congrats! You just wrote your first KUnit test! Next Steps ========== -* Check out the :doc:`tips` page for tips on +* Check out the Documentation/dev-tools/kunit/tips.rst page for tips on writing idiomatic KUnit tests. * Optional: see the :doc:`usage` page for a more in-depth explanation of KUnit. diff --git a/Documentation/dev-tools/kunit/tips.rst b/Documentation/dev-tools/kunit/tips.rst index 8d8c238f7f79..af3c10a44050 100644 --- a/Documentation/dev-tools/kunit/tips.rst +++ b/Documentation/dev-tools/kunit/tips.rst @@ -125,7 +125,7 @@ Here's a slightly in-depth example of how one could implement "mocking": Note: here we're able to get away with using ``test->priv``, but if you wanted -something more flexible you could use a named ``kunit_resource``, see :doc:`api/test`. +something more flexible you could use a named ``kunit_resource``, see Documentation/dev-tools/kunit/api/test.rst. Failing the current test ------------------------ @@ -185,5 +185,5 @@ Alternatively, one can take full control over the error message by using ``KUNIT Next Steps ========== -* Optional: see the :doc:`usage` page for a more +* Optional: see the Documentation/dev-tools/kunit/usage.rst page for a more in-depth explanation of KUnit. diff --git a/Documentation/dev-tools/kunit/usage.rst b/Documentation/dev-tools/kunit/usage.rst index 650f99590df5..3f6490fbeb95 100644 --- a/Documentation/dev-tools/kunit/usage.rst +++ b/Documentation/dev-tools/kunit/usage.rst @@ -10,7 +10,7 @@ understand it. This guide assumes a working knowledge of the Linux kernel and some basic knowledge of testing. For a high level introduction to KUnit, including setting up KUnit for your -project, see :doc:`start`. +project, see Documentation/dev-tools/kunit/start.rst. Organization of this document ============================= @@ -99,7 +99,7 @@ violated; however, the test will continue running, potentially trying other expectations until the test case ends or is otherwise terminated. This is as opposed to *assertions* which are discussed later. -To learn about more expectations supported by KUnit, see :doc:`api/test`. +To learn about more expectations supported by KUnit, see Documentation/dev-tools/kunit/api/test.rst. .. note:: A single test case should be pretty short, pretty easy to understand, @@ -216,7 +216,7 @@ test suite in a special linker section so that it can be run by KUnit either after late_init, or when the test module is loaded (depending on whether the test was built in or not). -For more information on these types of things see the :doc:`api/test`. +For more information on these types of things see the Documentation/dev-tools/kunit/api/test.rst. Common Patterns =============== </patch> Still, there's one hunk that would conflict between docs-next and linux-next. I'll send this one in separate, during the -rc1 week, in order to solve the remaining :doc: occurrence. Thanks! Mauro > > Reviewed-by: David Gow <davidgow@google.com> > > Cheers, > -- David > > > > > Documentation/dev-tools/kunit/faq.rst | 2 +- > > Documentation/dev-tools/kunit/index.rst | 14 +++++++------- > > Documentation/dev-tools/kunit/start.rst | 6 +++--- > > Documentation/dev-tools/kunit/tips.rst | 5 +++-- > > Documentation/dev-tools/kunit/usage.rst | 8 +++++--- > > 5 files changed, 19 insertions(+), 16 deletions(-) > > > > diff --git a/Documentation/dev-tools/kunit/faq.rst b/Documentation/dev-tools/kunit/faq.rst > > index 8d5029ad210a..5c6555d020f3 100644 > > --- a/Documentation/dev-tools/kunit/faq.rst > > +++ b/Documentation/dev-tools/kunit/faq.rst > > @@ -97,7 +97,7 @@ things to try. > > modules will automatically execute associated tests when loaded. Test results > > can be collected from ``/sys/kernel/debug/kunit/<test suite>/results``, and > > can be parsed with ``kunit.py parse``. For more details, see "KUnit on > > - non-UML architectures" in :doc:`usage`. > > + non-UML architectures" in Documentation/dev-tools/kunit/usage.rst. > > > > If none of the above tricks help, you are always welcome to email any issues to > > kunit-dev@googlegroups.com. > > diff --git a/Documentation/dev-tools/kunit/index.rst b/Documentation/dev-tools/kunit/index.rst > > index 848478838347..25d92a9a05ea 100644 > > --- a/Documentation/dev-tools/kunit/index.rst > > +++ b/Documentation/dev-tools/kunit/index.rst > > @@ -36,7 +36,7 @@ To make running these tests (and reading the results) easier, KUnit offers > > results. This provides a quick way of running KUnit tests during development, > > without requiring a virtual machine or separate hardware. > > > > -Get started now: :doc:`start` > > +Get started now: Documentation/dev-tools/kunit/start.rst > > > > Why KUnit? > > ========== > > @@ -88,9 +88,9 @@ it takes to read their test log? > > How do I use it? > > ================ > > > > -* :doc:`start` - for new users of KUnit > > -* :doc:`tips` - for short examples of best practices > > -* :doc:`usage` - for a more detailed explanation of KUnit features > > -* :doc:`api/index` - for the list of KUnit APIs used for testing > > -* :doc:`kunit-tool` - for more information on the kunit_tool helper script > > -* :doc:`faq` - for answers to some common questions about KUnit > > +* Documentation/dev-tools/kunit/start.rst - for new users of KUnit > > +* Documentation/dev-tools/kunit/tips.rst - for short examples of best practices > > +* Documentation/dev-tools/kunit/usage.rst - for a more detailed explanation of KUnit features > > +* Documentation/dev-tools/kunit/api/index.rst - for the list of KUnit APIs used for testing > > +* Documentation/dev-tools/kunit/kunit-tool.rst - for more information on the kunit_tool helper script > > +* Documentation/dev-tools/kunit/faq.rst - for answers to some common questions about KUnit > > diff --git a/Documentation/dev-tools/kunit/start.rst b/Documentation/dev-tools/kunit/start.rst > > index 0e65cabe08eb..ee21e482a0de 100644 > > --- a/Documentation/dev-tools/kunit/start.rst > > +++ b/Documentation/dev-tools/kunit/start.rst > > @@ -21,7 +21,7 @@ The wrapper can be run with: > > ./tools/testing/kunit/kunit.py run > > > > For more information on this wrapper (also called kunit_tool) check out the > > -:doc:`kunit-tool` page. > > +Documentation/dev-tools/kunit/kunit-tool.rst page. > > > > Creating a .kunitconfig > > ----------------------- > > @@ -234,7 +234,7 @@ Congrats! You just wrote your first KUnit test! > > > > Next Steps > > ========== > > -* Check out the :doc:`tips` page for tips on > > +* Check out the Documentation/dev-tools/kunit/tips.rst page for tips on > > writing idiomatic KUnit tests. > > -* Optional: see the :doc:`usage` page for a more > > +* Optional: see the Documentation/dev-tools/kunit/usage.rst page for a more > > in-depth explanation of KUnit. > > diff --git a/Documentation/dev-tools/kunit/tips.rst b/Documentation/dev-tools/kunit/tips.rst > > index 8d8c238f7f79..492d2ded2f5a 100644 > > --- a/Documentation/dev-tools/kunit/tips.rst > > +++ b/Documentation/dev-tools/kunit/tips.rst > > @@ -125,7 +125,8 @@ Here's a slightly in-depth example of how one could implement "mocking": > > > > > > Note: here we're able to get away with using ``test->priv``, but if you wanted > > -something more flexible you could use a named ``kunit_resource``, see :doc:`api/test`. > > +something more flexible you could use a named ``kunit_resource``, see > > +Documentation/dev-tools/kunit/api/test.rst. > > > > Failing the current test > > ------------------------ > > @@ -185,5 +186,5 @@ Alternatively, one can take full control over the error message by using ``KUNIT > > > > Next Steps > > ========== > > -* Optional: see the :doc:`usage` page for a more > > +* Optional: see the Documentation/dev-tools/kunit/usage.rst page for a more > > in-depth explanation of KUnit. > > diff --git a/Documentation/dev-tools/kunit/usage.rst b/Documentation/dev-tools/kunit/usage.rst > > index 650f99590df5..3ee7ab91f712 100644 > > --- a/Documentation/dev-tools/kunit/usage.rst > > +++ b/Documentation/dev-tools/kunit/usage.rst > > @@ -10,7 +10,7 @@ understand it. This guide assumes a working knowledge of the Linux kernel and > > some basic knowledge of testing. > > > > For a high level introduction to KUnit, including setting up KUnit for your > > -project, see :doc:`start`. > > +project, see Documentation/dev-tools/kunit/start.rst. > > > > Organization of this document > > ============================= > > @@ -99,7 +99,8 @@ violated; however, the test will continue running, potentially trying other > > expectations until the test case ends or is otherwise terminated. This is as > > opposed to *assertions* which are discussed later. > > > > -To learn about more expectations supported by KUnit, see :doc:`api/test`. > > +To learn about more expectations supported by KUnit, see > > +Documentation/dev-tools/kunit/api/test.rst. > > > > .. note:: > > A single test case should be pretty short, pretty easy to understand, > > @@ -216,7 +217,8 @@ test suite in a special linker section so that it can be run by KUnit either > > after late_init, or when the test module is loaded (depending on whether the > > test was built in or not). > > > > -For more information on these types of things see the :doc:`api/test`. > > +For more information on these types of things see the > > +Documentation/dev-tools/kunit/api/test.rst. > > > > Common Patterns > > =============== > > -- > > 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/a3ad84108a5b254e545f88e58d411f5fe2e25c7e.1622898327.git.mchehab%2Bhuawei%40kernel.org. Thanks, Mauro ^ permalink raw reply related [flat|nested] 17+ messages in thread
* Re: [PATCH 14/34] docs: dev-tools: kunit: avoid using ReST :doc:`foo` markup 2021-06-16 6:00 ` Mauro Carvalho Chehab @ 2021-06-16 6:13 ` Mauro Carvalho Chehab 0 siblings, 0 replies; 17+ messages in thread From: Mauro Carvalho Chehab @ 2021-06-16 6:13 UTC (permalink / raw) To: David Gow Cc: Jonathan Corbet, Linux Doc Mailing List, Brendan Higgins, KUnit Development, Linux Kernel Mailing List, open list:KERNEL SELFTEST FRAMEWORK Em Wed, 16 Jun 2021 08:00:34 +0200 Mauro Carvalho Chehab <mchehab+huawei@kernel.org> escreveu: > Em Sat, 5 Jun 2021 23:44:41 +0800 > David Gow <davidgow@google.com> escreveu: > > > On Sat, Jun 5, 2021 at 9:18 PM Mauro Carvalho Chehab > > <mchehab+huawei@kernel.org> wrote: > > > > > > The :doc:`foo` tag is auto-generated via automarkup.py. > > > So, use the filename at the sources, instead of :doc:`foo`. > > > > > > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> > > > --- > > > > This is much better, thanks! Do note that there's a merge conflict > > (and another :doc:`` tag which needs updating) in the kunit-fixes > > branch: > > https://git.kernel.org/pub/scm/linux/kernel/git/shuah/linux-kselftest.git/commit/?h=kunit-fixes&id=11dbc62a73a7da9f3697e8ce83d07503c11dcabb > > Ok, thanks for the warning. I'm folding the enclosed patch: Err... ended adding a wrong diff there... I guess I'm missing my morning dosage of caffeine ;-) The diff I appended is this one: diff --git a/Documentation/dev-tools/kunit/start.rst b/Documentation/dev-tools/kunit/start.rst index ee21e482a0de..63ef7b625c13 100644 --- a/Documentation/dev-tools/kunit/start.rst +++ b/Documentation/dev-tools/kunit/start.rst @@ -236,5 +236,5 @@ Next Steps ========== * Check out the Documentation/dev-tools/kunit/tips.rst page for tips on writing idiomatic KUnit tests. -* Optional: see the Documentation/dev-tools/kunit/usage.rst page for a more +* Optional: see the :doc:`usage` page for a more in-depth explanation of KUnit. It basically reverts a change in order to avoid merge conflicts at linux-next when this patch gets merged via docs-next. I'll submit later a followup patch against 5.14-rc1. Thanks, Mauro ^ permalink raw reply related [flat|nested] 17+ messages in thread
* Re: [PATCH 14/34] docs: dev-tools: kunit: avoid using ReST :doc:`foo` markup 2021-06-05 13:18 ` [PATCH 14/34] docs: dev-tools: kunit: avoid using ReST :doc:`foo` markup Mauro Carvalho Chehab 2021-06-05 15:44 ` David Gow @ 2021-06-07 20:20 ` Brendan Higgins 1 sibling, 0 replies; 17+ messages in thread From: Brendan Higgins @ 2021-06-07 20:20 UTC (permalink / raw) To: Mauro Carvalho Chehab Cc: Jonathan Corbet, Linux Doc Mailing List, KUnit Development, Linux Kernel Mailing List, open list:KERNEL SELFTEST FRAMEWORK On Sat, Jun 5, 2021 at 6:18 AM Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote: > > The :doc:`foo` tag is auto-generated via automarkup.py. > So, use the filename at the sources, instead of :doc:`foo`. > > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Thanks! Acked-by: Brendan Higgins <brendanhiggins@google.com> ^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag 2021-06-05 13:17 [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag Mauro Carvalho Chehab 2021-06-05 13:18 ` [PATCH 02/34] docs: dev-tools: kunit: don't use a table for docs name Mauro Carvalho Chehab 2021-06-05 13:18 ` [PATCH 14/34] docs: dev-tools: kunit: avoid using ReST :doc:`foo` markup Mauro Carvalho Chehab @ 2021-06-05 13:37 ` Mauro Carvalho Chehab 2021-06-05 15:11 ` Nícolas F. R. A. Prado 3 siblings, 0 replies; 17+ messages in thread From: Mauro Carvalho Chehab @ 2021-06-05 13:37 UTC (permalink / raw) To: Jonathan Corbet, Linux Doc Mailing List Cc: linux-kernel, bpf, coresight, devicetree, kunit-dev, kvm, linux-acpi, linux-arm-kernel, linux-gpio, linux-hwmon, linux-i2c, linux-kselftest, linux-media, linux-pci, linux-pm, linux-security-module, netdev Em Sat, 5 Jun 2021 15:17:59 +0200 Mauro Carvalho Chehab <mchehab+huawei@kernel.org> escreveu: > As discussed at: > https://lore.kernel.org/linux-doc/871r9k6rmy.fsf@meer.lwn.net/ > > It is better to avoid using :doc:`foo` to refer to Documentation/foo.rst, as the > automarkup.py extension should handle it automatically, on most cases. Forgot to mention: 1. this series is against docs-next branch; 2. maintainers bcc, as otherwise the e-mail would be rejected, due to the number of c/c. I opted to keep c/c the mailing lists. Regards, Mauro > > There are a couple of exceptions to this rule: > > 1. when :doc: tag is used to point to a kernel-doc DOC: markup; > 2. when it is used with a named tag, e. g. :doc:`some name <foo>`; > > It should also be noticed that automarkup.py has currently an issue: > if one use a markup like: > > Documentation/dev-tools/kunit/api/test.rst > - documents all of the standard testing API excluding mocking > or mocking related features. > > or, even: > > Documentation/dev-tools/kunit/api/test.rst > documents all of the standard testing API excluding mocking > or mocking related features. > > The automarkup.py will simply ignore it. Not sure why. This patch series > avoid the above patterns (which is present only on 4 files), but it would be > nice to have a followup patch fixing the issue at automarkup.py. > > On this series: > > Patch 1 manually adjust the references inside driver-api/pm/devices.rst, > as there it uses :file:`foo` to refer to some Documentation/ files; > > Patch 2 converts a table at Documentation/dev-tools/kunit/api/index.rst > into a list, carefully avoiding the > > Patch 3 converts the cross-references at the media documentation, also > avoiding the automarkup.py bug; > > Patches 4-34 convert the other occurrences via a replace script. They were > manually edited, in order to honour 80-columns where possible. > > I did a diff between the Sphinx 2.4.4 output before and after this patch > series in order to double-check that all converted Documentation/ > references will produce <a href=<foo>.rst>foo title</a> tags. > > Mauro Carvalho Chehab (34): > docs: devices.rst: better reference documentation docs > docs: dev-tools: kunit: don't use a table for docs name > media: docs: */media/index.rst: don't use ReST doc:`foo` > media: userspace-api: avoid using ReST :doc:`foo` markup > media: driver-api: drivers: avoid using ReST :doc:`foo` markup > media: admin-guide: avoid using ReST :doc:`foo` markup > docs: admin-guide: pm: avoid using ReSt :doc:`foo` markup > docs: admin-guide: hw-vuln: avoid using ReST :doc:`foo` markup > docs: admin-guide: sysctl: avoid using ReST :doc:`foo` markup > docs: block: biodoc.rst: avoid using ReSt :doc:`foo` markup > docs: bpf: bpf_lsm.rst: avoid using ReSt :doc:`foo` markup > docs: core-api: avoid using ReSt :doc:`foo` markup > docs: dev-tools: testing-overview.rst: avoid using ReSt :doc:`foo` > markup > docs: dev-tools: kunit: avoid using ReST :doc:`foo` markup > docs: devicetree: bindings: submitting-patches.rst: avoid using ReSt > :doc:`foo` markup > docs: doc-guide: avoid using ReSt :doc:`foo` markup > docs: driver-api: avoid using ReSt :doc:`foo` markup > docs: driver-api: gpio: using-gpio.rst: avoid using ReSt :doc:`foo` > markup > docs: driver-api: surface_aggregator: avoid using ReSt :doc:`foo` > markup > docs: driver-api: usb: avoid using ReSt :doc:`foo` markup > docs: firmware-guide: acpi: avoid using ReSt :doc:`foo` markup > docs: hwmon: adm1177.rst: avoid using ReSt :doc:`foo` markup > docs: i2c: avoid using ReSt :doc:`foo` markup > docs: kernel-hacking: hacking.rst: avoid using ReSt :doc:`foo` markup > docs: networking: devlink: avoid using ReSt :doc:`foo` markup > docs: PCI: endpoint: pci-endpoint-cfs.rst: avoid using ReSt :doc:`foo` > markup > docs: PCI: pci.rst: avoid using ReSt :doc:`foo` markup > docs: process: submitting-patches.rst: avoid using ReSt :doc:`foo` > markup > docs: security: landlock.rst: avoid using ReSt :doc:`foo` markup > docs: trace: coresight: coresight.rst: avoid using ReSt :doc:`foo` > markup > docs: trace: ftrace.rst: avoid using ReSt :doc:`foo` markup > docs: userspace-api: landlock.rst: avoid using ReSt :doc:`foo` markup > docs: virt: kvm: s390-pv-boot.rst: avoid using ReSt :doc:`foo` markup > docs: x86: avoid using ReSt :doc:`foo` markup > > .../PCI/endpoint/pci-endpoint-cfs.rst | 2 +- > Documentation/PCI/pci.rst | 6 +-- > .../special-register-buffer-data-sampling.rst | 3 +- > Documentation/admin-guide/media/bt8xx.rst | 15 ++++---- > Documentation/admin-guide/media/bttv.rst | 21 ++++++----- > Documentation/admin-guide/media/index.rst | 12 +++--- > Documentation/admin-guide/media/saa7134.rst | 3 +- > Documentation/admin-guide/pm/intel_idle.rst | 16 +++++--- > Documentation/admin-guide/pm/intel_pstate.rst | 9 +++-- > Documentation/admin-guide/sysctl/abi.rst | 2 +- > Documentation/admin-guide/sysctl/kernel.rst | 37 ++++++++++--------- > Documentation/block/biodoc.rst | 2 +- > Documentation/bpf/bpf_lsm.rst | 13 ++++--- > .../core-api/bus-virt-phys-mapping.rst | 2 +- > Documentation/core-api/dma-api.rst | 5 ++- > Documentation/core-api/dma-isa-lpc.rst | 2 +- > Documentation/core-api/index.rst | 4 +- > Documentation/dev-tools/kunit/api/index.rst | 8 ++-- > Documentation/dev-tools/kunit/faq.rst | 2 +- > Documentation/dev-tools/kunit/index.rst | 14 +++---- > Documentation/dev-tools/kunit/start.rst | 6 +-- > Documentation/dev-tools/kunit/tips.rst | 5 ++- > Documentation/dev-tools/kunit/usage.rst | 8 ++-- > Documentation/dev-tools/testing-overview.rst | 16 ++++---- > .../bindings/submitting-patches.rst | 11 +++--- > Documentation/doc-guide/contributing.rst | 8 ++-- > Documentation/driver-api/gpio/using-gpio.rst | 4 +- > Documentation/driver-api/ioctl.rst | 2 +- > .../driver-api/media/drivers/bttv-devel.rst | 2 +- > Documentation/driver-api/media/index.rst | 10 +++-- > Documentation/driver-api/pm/devices.rst | 8 ++-- > .../surface_aggregator/clients/index.rst | 3 +- > .../surface_aggregator/internal.rst | 15 ++++---- > .../surface_aggregator/overview.rst | 6 ++- > Documentation/driver-api/usb/dma.rst | 6 +-- > .../acpi/dsd/data-node-references.rst | 3 +- > .../firmware-guide/acpi/dsd/graph.rst | 2 +- > .../firmware-guide/acpi/enumeration.rst | 7 ++-- > Documentation/hwmon/adm1177.rst | 3 +- > Documentation/i2c/instantiating-devices.rst | 2 +- > Documentation/i2c/old-module-parameters.rst | 3 +- > Documentation/i2c/smbus-protocol.rst | 4 +- > Documentation/kernel-hacking/hacking.rst | 4 +- > .../networking/devlink/devlink-region.rst | 2 +- > .../networking/devlink/devlink-trap.rst | 4 +- > Documentation/process/submitting-patches.rst | 32 ++++++++-------- > Documentation/security/landlock.rst | 3 +- > Documentation/trace/coresight/coresight.rst | 8 ++-- > Documentation/trace/ftrace.rst | 2 +- > Documentation/userspace-api/landlock.rst | 11 +++--- > .../userspace-api/media/glossary.rst | 2 +- > Documentation/userspace-api/media/index.rst | 12 +++--- > Documentation/virt/kvm/s390-pv-boot.rst | 2 +- > Documentation/x86/boot.rst | 4 +- > Documentation/x86/mtrr.rst | 2 +- > 55 files changed, 217 insertions(+), 183 deletions(-) > Thanks, Mauro ^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag 2021-06-05 13:17 [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag Mauro Carvalho Chehab ` (2 preceding siblings ...) 2021-06-05 13:37 ` [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag Mauro Carvalho Chehab @ 2021-06-05 15:11 ` Nícolas F. R. A. Prado 2021-06-05 19:08 ` Mauro Carvalho Chehab 3 siblings, 1 reply; 17+ messages in thread From: Nícolas F. R. A. Prado @ 2021-06-05 15:11 UTC (permalink / raw) To: Mauro Carvalho Chehab Cc: Jonathan Corbet, Linux Doc Mailing List, linux-kernel, bpf, coresight, devicetree, kunit-dev, kvm, linux-acpi, linux-arm-kernel, linux-gpio, linux-hwmon, linux-i2c, linux-kselftest, linux-media, linux-pci, linux-pm, linux-security-module, netdev Hi Mauro, On Sat, Jun 05, 2021 at 03:17:59PM +0200, Mauro Carvalho Chehab wrote: > As discussed at: > https://lore.kernel.org/linux-doc/871r9k6rmy.fsf@meer.lwn.net/ > > It is better to avoid using :doc:`foo` to refer to Documentation/foo.rst, as the > automarkup.py extension should handle it automatically, on most cases. > > There are a couple of exceptions to this rule: > > 1. when :doc: tag is used to point to a kernel-doc DOC: markup; > 2. when it is used with a named tag, e. g. :doc:`some name <foo>`; > > It should also be noticed that automarkup.py has currently an issue: > if one use a markup like: > > Documentation/dev-tools/kunit/api/test.rst > - documents all of the standard testing API excluding mocking > or mocking related features. > > or, even: > > Documentation/dev-tools/kunit/api/test.rst > documents all of the standard testing API excluding mocking > or mocking related features. > > The automarkup.py will simply ignore it. Not sure why. This patch series > avoid the above patterns (which is present only on 4 files), but it would be > nice to have a followup patch fixing the issue at automarkup.py. What I think is happening here is that we're using rST's syntax for definition lists [1]. automarkup.py ignores literal nodes, and perhaps a definition is considered a literal by Sphinx. Adding a blank line after the Documentation/... or removing the additional indentation makes it work, like you did in your 2nd and 3rd patch, since then it's not a definition anymore, although then the visual output is different as well. I'm not sure this is something we need to fix. Does it make sense to use definition lists for links like that? If it does, I guess one option would be to whitelist definition lists so they aren't ignored by automarkup, but I feel this could get ugly really quickly. FWIW note that it's also possible to use relative paths to docs with automarkup. Thanks, Nícolas [1] https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#definition-lists > > On this series: > > Patch 1 manually adjust the references inside driver-api/pm/devices.rst, > as there it uses :file:`foo` to refer to some Documentation/ files; > > Patch 2 converts a table at Documentation/dev-tools/kunit/api/index.rst > into a list, carefully avoiding the > > Patch 3 converts the cross-references at the media documentation, also > avoiding the automarkup.py bug; > > Patches 4-34 convert the other occurrences via a replace script. They were > manually edited, in order to honour 80-columns where possible. > > I did a diff between the Sphinx 2.4.4 output before and after this patch > series in order to double-check that all converted Documentation/ > references will produce <a href=<foo>.rst>foo title</a> tags. > > Mauro Carvalho Chehab (34): > docs: devices.rst: better reference documentation docs > docs: dev-tools: kunit: don't use a table for docs name > media: docs: */media/index.rst: don't use ReST doc:`foo` > media: userspace-api: avoid using ReST :doc:`foo` markup > media: driver-api: drivers: avoid using ReST :doc:`foo` markup > media: admin-guide: avoid using ReST :doc:`foo` markup > docs: admin-guide: pm: avoid using ReSt :doc:`foo` markup > docs: admin-guide: hw-vuln: avoid using ReST :doc:`foo` markup > docs: admin-guide: sysctl: avoid using ReST :doc:`foo` markup > docs: block: biodoc.rst: avoid using ReSt :doc:`foo` markup > docs: bpf: bpf_lsm.rst: avoid using ReSt :doc:`foo` markup > docs: core-api: avoid using ReSt :doc:`foo` markup > docs: dev-tools: testing-overview.rst: avoid using ReSt :doc:`foo` > markup > docs: dev-tools: kunit: avoid using ReST :doc:`foo` markup > docs: devicetree: bindings: submitting-patches.rst: avoid using ReSt > :doc:`foo` markup > docs: doc-guide: avoid using ReSt :doc:`foo` markup > docs: driver-api: avoid using ReSt :doc:`foo` markup > docs: driver-api: gpio: using-gpio.rst: avoid using ReSt :doc:`foo` > markup > docs: driver-api: surface_aggregator: avoid using ReSt :doc:`foo` > markup > docs: driver-api: usb: avoid using ReSt :doc:`foo` markup > docs: firmware-guide: acpi: avoid using ReSt :doc:`foo` markup > docs: hwmon: adm1177.rst: avoid using ReSt :doc:`foo` markup > docs: i2c: avoid using ReSt :doc:`foo` markup > docs: kernel-hacking: hacking.rst: avoid using ReSt :doc:`foo` markup > docs: networking: devlink: avoid using ReSt :doc:`foo` markup > docs: PCI: endpoint: pci-endpoint-cfs.rst: avoid using ReSt :doc:`foo` > markup > docs: PCI: pci.rst: avoid using ReSt :doc:`foo` markup > docs: process: submitting-patches.rst: avoid using ReSt :doc:`foo` > markup > docs: security: landlock.rst: avoid using ReSt :doc:`foo` markup > docs: trace: coresight: coresight.rst: avoid using ReSt :doc:`foo` > markup > docs: trace: ftrace.rst: avoid using ReSt :doc:`foo` markup > docs: userspace-api: landlock.rst: avoid using ReSt :doc:`foo` markup > docs: virt: kvm: s390-pv-boot.rst: avoid using ReSt :doc:`foo` markup > docs: x86: avoid using ReSt :doc:`foo` markup > > .../PCI/endpoint/pci-endpoint-cfs.rst | 2 +- > Documentation/PCI/pci.rst | 6 +-- > .../special-register-buffer-data-sampling.rst | 3 +- > Documentation/admin-guide/media/bt8xx.rst | 15 ++++---- > Documentation/admin-guide/media/bttv.rst | 21 ++++++----- > Documentation/admin-guide/media/index.rst | 12 +++--- > Documentation/admin-guide/media/saa7134.rst | 3 +- > Documentation/admin-guide/pm/intel_idle.rst | 16 +++++--- > Documentation/admin-guide/pm/intel_pstate.rst | 9 +++-- > Documentation/admin-guide/sysctl/abi.rst | 2 +- > Documentation/admin-guide/sysctl/kernel.rst | 37 ++++++++++--------- > Documentation/block/biodoc.rst | 2 +- > Documentation/bpf/bpf_lsm.rst | 13 ++++--- > .../core-api/bus-virt-phys-mapping.rst | 2 +- > Documentation/core-api/dma-api.rst | 5 ++- > Documentation/core-api/dma-isa-lpc.rst | 2 +- > Documentation/core-api/index.rst | 4 +- > Documentation/dev-tools/kunit/api/index.rst | 8 ++-- > Documentation/dev-tools/kunit/faq.rst | 2 +- > Documentation/dev-tools/kunit/index.rst | 14 +++---- > Documentation/dev-tools/kunit/start.rst | 6 +-- > Documentation/dev-tools/kunit/tips.rst | 5 ++- > Documentation/dev-tools/kunit/usage.rst | 8 ++-- > Documentation/dev-tools/testing-overview.rst | 16 ++++---- > .../bindings/submitting-patches.rst | 11 +++--- > Documentation/doc-guide/contributing.rst | 8 ++-- > Documentation/driver-api/gpio/using-gpio.rst | 4 +- > Documentation/driver-api/ioctl.rst | 2 +- > .../driver-api/media/drivers/bttv-devel.rst | 2 +- > Documentation/driver-api/media/index.rst | 10 +++-- > Documentation/driver-api/pm/devices.rst | 8 ++-- > .../surface_aggregator/clients/index.rst | 3 +- > .../surface_aggregator/internal.rst | 15 ++++---- > .../surface_aggregator/overview.rst | 6 ++- > Documentation/driver-api/usb/dma.rst | 6 +-- > .../acpi/dsd/data-node-references.rst | 3 +- > .../firmware-guide/acpi/dsd/graph.rst | 2 +- > .../firmware-guide/acpi/enumeration.rst | 7 ++-- > Documentation/hwmon/adm1177.rst | 3 +- > Documentation/i2c/instantiating-devices.rst | 2 +- > Documentation/i2c/old-module-parameters.rst | 3 +- > Documentation/i2c/smbus-protocol.rst | 4 +- > Documentation/kernel-hacking/hacking.rst | 4 +- > .../networking/devlink/devlink-region.rst | 2 +- > .../networking/devlink/devlink-trap.rst | 4 +- > Documentation/process/submitting-patches.rst | 32 ++++++++-------- > Documentation/security/landlock.rst | 3 +- > Documentation/trace/coresight/coresight.rst | 8 ++-- > Documentation/trace/ftrace.rst | 2 +- > Documentation/userspace-api/landlock.rst | 11 +++--- > .../userspace-api/media/glossary.rst | 2 +- > Documentation/userspace-api/media/index.rst | 12 +++--- > Documentation/virt/kvm/s390-pv-boot.rst | 2 +- > Documentation/x86/boot.rst | 4 +- > Documentation/x86/mtrr.rst | 2 +- > 55 files changed, 217 insertions(+), 183 deletions(-) > > -- > 2.31.1 > > ^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag 2021-06-05 15:11 ` Nícolas F. R. A. Prado @ 2021-06-05 19:08 ` Mauro Carvalho Chehab 2021-06-06 22:52 ` Nícolas F. R. A. Prado 0 siblings, 1 reply; 17+ messages in thread From: Mauro Carvalho Chehab @ 2021-06-05 19:08 UTC (permalink / raw) To: Nícolas F. R. A. Prado Cc: Jonathan Corbet, Linux Doc Mailing List, linux-kernel, bpf, coresight, devicetree, kunit-dev, kvm, linux-acpi, linux-arm-kernel, linux-gpio, linux-hwmon, linux-i2c, linux-kselftest, linux-media, linux-pci, linux-pm, linux-security-module, netdev Em Sat, 5 Jun 2021 12:11:09 -0300 Nícolas F. R. A. Prado <n@nfraprado.net> escreveu: > Hi Mauro, > > On Sat, Jun 05, 2021 at 03:17:59PM +0200, Mauro Carvalho Chehab wrote: > > As discussed at: > > https://lore.kernel.org/linux-doc/871r9k6rmy.fsf@meer.lwn.net/ > > > > It is better to avoid using :doc:`foo` to refer to Documentation/foo.rst, as the > > automarkup.py extension should handle it automatically, on most cases. > > > > There are a couple of exceptions to this rule: > > > > 1. when :doc: tag is used to point to a kernel-doc DOC: markup; > > 2. when it is used with a named tag, e. g. :doc:`some name <foo>`; > > > > It should also be noticed that automarkup.py has currently an issue: > > if one use a markup like: > > > > Documentation/dev-tools/kunit/api/test.rst > > - documents all of the standard testing API excluding mocking > > or mocking related features. > > > > or, even: > > > > Documentation/dev-tools/kunit/api/test.rst > > documents all of the standard testing API excluding mocking > > or mocking related features. > > > > The automarkup.py will simply ignore it. Not sure why. This patch series > > avoid the above patterns (which is present only on 4 files), but it would be > > nice to have a followup patch fixing the issue at automarkup.py. > > What I think is happening here is that we're using rST's syntax for definition > lists [1]. automarkup.py ignores literal nodes, and perhaps a definition is > considered a literal by Sphinx. Adding a blank line after the Documentation/... > or removing the additional indentation makes it work, like you did in your > 2nd and 3rd patch, since then it's not a definition anymore, although then the > visual output is different as well. A literal has a different output. I think that this is not the case, but I didn't check the python code from docutils/Sphinx. > I'm not sure this is something we need to fix. Does it make sense to use > definition lists for links like that? If it does, I guess one option would be to > whitelist definition lists so they aren't ignored by automarkup, but I feel > this could get ugly really quickly. Yes, we should avoid handling literal blocks, as this can be a nightmare. > FWIW note that it's also possible to use relative paths to docs with automarkup. Not sure if you meant to say using something like ../driver-api/foo.rst. If so, relative paths are a problem, as it will pass unnoticed by this script: ./scripts/documentation-file-ref-check which is meant to warn when a file is moved to be elsewhere. Ok, it could be taught to use "../" to identify paths, but I suspect that this could lead to false positives, like here: Documentation/usb/gadget-testing.rst: # ln -s ../../uncompressed/u Documentation/usb/gadget-testing.rst: # cd ../../class/fs Documentation/usb/gadget-testing.rst: # ln -s ../../header/h If you meant, instead, :doc:`../foo`, this series address those too. Regards, Mauro ^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag 2021-06-05 19:08 ` Mauro Carvalho Chehab @ 2021-06-06 22:52 ` Nícolas F. R. A. Prado 2021-06-07 7:34 ` Mauro Carvalho Chehab 0 siblings, 1 reply; 17+ messages in thread From: Nícolas F. R. A. Prado @ 2021-06-06 22:52 UTC (permalink / raw) To: Mauro Carvalho Chehab Cc: Jonathan Corbet, Linux Doc Mailing List, linux-kernel, bpf, coresight, devicetree, kunit-dev, kvm, linux-acpi, linux-arm-kernel, linux-gpio, linux-hwmon, linux-i2c, linux-kselftest, linux-media, linux-pci, linux-pm, linux-security-module, netdev On Sat, Jun 05, 2021 at 09:08:36PM +0200, Mauro Carvalho Chehab wrote: > Em Sat, 5 Jun 2021 12:11:09 -0300 > Nícolas F. R. A. Prado <n@nfraprado.net> escreveu: > > > Hi Mauro, > > > > On Sat, Jun 05, 2021 at 03:17:59PM +0200, Mauro Carvalho Chehab wrote: > > > As discussed at: > > > https://lore.kernel.org/linux-doc/871r9k6rmy.fsf@meer.lwn.net/ > > > > > > It is better to avoid using :doc:`foo` to refer to Documentation/foo.rst, as the > > > automarkup.py extension should handle it automatically, on most cases. > > > > > > There are a couple of exceptions to this rule: > > > > > > 1. when :doc: tag is used to point to a kernel-doc DOC: markup; > > > 2. when it is used with a named tag, e. g. :doc:`some name <foo>`; > > > > > > It should also be noticed that automarkup.py has currently an issue: > > > if one use a markup like: > > > > > > Documentation/dev-tools/kunit/api/test.rst > > > - documents all of the standard testing API excluding mocking > > > or mocking related features. > > > > > > or, even: > > > > > > Documentation/dev-tools/kunit/api/test.rst > > > documents all of the standard testing API excluding mocking > > > or mocking related features. > > > > > > The automarkup.py will simply ignore it. Not sure why. This patch series > > > avoid the above patterns (which is present only on 4 files), but it would be > > > nice to have a followup patch fixing the issue at automarkup.py. > > > > What I think is happening here is that we're using rST's syntax for definition > > lists [1]. automarkup.py ignores literal nodes, and perhaps a definition is > > considered a literal by Sphinx. Adding a blank line after the Documentation/... > > or removing the additional indentation makes it work, like you did in your > > 2nd and 3rd patch, since then it's not a definition anymore, although then the > > visual output is different as well. > > A literal has a different output. I think that this is not the case, but I > didn't check the python code from docutils/Sphinx. Okay, I went in deeper to understand the issue and indeed it wasn't what I thought. The reason definitions are ignored by automarkup.py is because the main loop iterates only over nodes that are of type paragraph: 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)) And inspecting the HTML output from your example, the definition name is inside a <dt> tag, and it doesn't have a <p> inside. So in summary, automarkup.py will only work on elements which are inside a <p> in the output. Only applying the automarkup inside paragraphs seems like a good decision (which covers text in lists and tables as well), so unless there are other types of elements without paragraphs where automarkup should work, I think we should just avoid using definition lists pointing to documents like that. > > > I'm not sure this is something we need to fix. Does it make sense to use > > definition lists for links like that? If it does, I guess one option would be to > > whitelist definition lists so they aren't ignored by automarkup, but I feel > > this could get ugly really quickly. > > Yes, we should avoid handling literal blocks, as this can be a nightmare. > > > FWIW note that it's also possible to use relative paths to docs with automarkup. > > Not sure if you meant to say using something like ../driver-api/foo.rst. > If so, relative paths are a problem, as it will pass unnoticed by this script: > > ./scripts/documentation-file-ref-check > > which is meant to warn when a file is moved to be elsewhere. Ok, it > could be taught to use "../" to identify paths, but I suspect that this > could lead to false positives, like here: > > Documentation/usb/gadget-testing.rst: # ln -s ../../uncompressed/u > Documentation/usb/gadget-testing.rst: # cd ../../class/fs > Documentation/usb/gadget-testing.rst: # ln -s ../../header/h Yes, that's what I meant. Ok, that makes sense. Although after automarkup.py starts printing warnings on missing references to files (which is a patch I still need to resend), it would work out-of-the-box with relative paths. automarkup wouldn't face that false positives issue since it ignores literal blocks, which isn't as easy for a standalone script. But that's still in the future, we can discuss what to do then after it is implemented, so full paths seem better for now. Thanks, Nícolas > > If you meant, instead, :doc:`../foo`, this series address those too. > > Regards, > Mauro ^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag 2021-06-06 22:52 ` Nícolas F. R. A. Prado @ 2021-06-07 7:34 ` Mauro Carvalho Chehab 2021-06-08 0:34 ` Nícolas F. R. A. Prado 0 siblings, 1 reply; 17+ messages in thread From: Mauro Carvalho Chehab @ 2021-06-07 7:34 UTC (permalink / raw) To: Nícolas F. R. A. Prado Cc: Jonathan Corbet, Linux Doc Mailing List, linux-kernel, bpf, coresight, devicetree, kunit-dev, kvm, linux-acpi, linux-arm-kernel, linux-gpio, linux-hwmon, linux-i2c, linux-kselftest, linux-media, linux-pci, linux-pm, linux-security-module, netdev Em Sun, 6 Jun 2021 19:52:25 -0300 Nícolas F. R. A. Prado <n@nfraprado.net> escreveu: > On Sat, Jun 05, 2021 at 09:08:36PM +0200, Mauro Carvalho Chehab wrote: > > Em Sat, 5 Jun 2021 12:11:09 -0300 > > Nícolas F. R. A. Prado <n@nfraprado.net> escreveu: > > > > > Hi Mauro, > > > > > > On Sat, Jun 05, 2021 at 03:17:59PM +0200, Mauro Carvalho Chehab wrote: > > > > As discussed at: > > > > https://lore.kernel.org/linux-doc/871r9k6rmy.fsf@meer.lwn.net/ > > > > > > > > It is better to avoid using :doc:`foo` to refer to Documentation/foo.rst, as the > > > > automarkup.py extension should handle it automatically, on most cases. > > > > > > > > There are a couple of exceptions to this rule: > > > > > > > > 1. when :doc: tag is used to point to a kernel-doc DOC: markup; > > > > 2. when it is used with a named tag, e. g. :doc:`some name <foo>`; > > > > > > > > It should also be noticed that automarkup.py has currently an issue: > > > > if one use a markup like: > > > > > > > > Documentation/dev-tools/kunit/api/test.rst > > > > - documents all of the standard testing API excluding mocking > > > > or mocking related features. > > > > > > > > or, even: > > > > > > > > Documentation/dev-tools/kunit/api/test.rst > > > > documents all of the standard testing API excluding mocking > > > > or mocking related features. > > > > > > > > The automarkup.py will simply ignore it. Not sure why. This patch series > > > > avoid the above patterns (which is present only on 4 files), but it would be > > > > nice to have a followup patch fixing the issue at automarkup.py. > > > > > > What I think is happening here is that we're using rST's syntax for definition > > > lists [1]. automarkup.py ignores literal nodes, and perhaps a definition is > > > considered a literal by Sphinx. Adding a blank line after the Documentation/... > > > or removing the additional indentation makes it work, like you did in your > > > 2nd and 3rd patch, since then it's not a definition anymore, although then the > > > visual output is different as well. > > > > A literal has a different output. I think that this is not the case, but I > > didn't check the python code from docutils/Sphinx. > > Okay, I went in deeper to understand the issue and indeed it wasn't what I > thought. The reason definitions are ignored by automarkup.py is because the main > loop iterates only over nodes that are of type paragraph: > > 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)) > > And inspecting the HTML output from your example, the definition name is inside > a <dt> tag, and it doesn't have a <p> inside. So in summary, automarkup.py will > only work on elements which are inside a <p> in the output. Yeah, that's what I was suspecting, based on the comments. Maybe something similar to the above could be done also for some non-paragraph data. By looking at: https://docutils.sourceforge.io/docs/ref/doctree.html It says that the body elements are: admonition, attention, block_quote, bullet_list, caution, citation, comment, compound, container, danger, definition_list, doctest_block, enumerated_list, error, field_list, figure, footnote, hint, image, important, line_block, literal_block, note, option_list, paragraph, pending, raw, rubric, substitution_definition, system_message, table, target, tip, warning So, perhaps a similar loop for definition_list would do the trick, but maybe automarkup should also look at other types, like enum lists, notes (and their variants, like error/warning) and footnotes. No idea how this would affect the docs build time, though. > Only applying the automarkup inside paragraphs seems like a good decision (which > covers text in lists and tables as well), so unless there are other types of > elements without paragraphs where automarkup should work, I think we should just > avoid using definition lists pointing to documents like that. Checking the code or doing some tests are needed for us to be sure about what of the above types docutils don't consider a paragraph. Thanks, Mauro ^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag 2021-06-07 7:34 ` Mauro Carvalho Chehab @ 2021-06-08 0:34 ` Nícolas F. R. A. Prado 2021-06-08 7:28 ` Mauro Carvalho Chehab 0 siblings, 1 reply; 17+ messages in thread From: Nícolas F. R. A. Prado @ 2021-06-08 0:34 UTC (permalink / raw) To: Mauro Carvalho Chehab Cc: Jonathan Corbet, Linux Doc Mailing List, linux-kernel, bpf, coresight, devicetree, kunit-dev, kvm, linux-acpi, linux-arm-kernel, linux-gpio, linux-hwmon, linux-i2c, linux-kselftest, linux-media, linux-pci, linux-pm, linux-security-module, netdev Hi Mauro, On Mon, Jun 07, 2021 at 09:34:22AM +0200, Mauro Carvalho Chehab wrote: > Em Sun, 6 Jun 2021 19:52:25 -0300 > Nícolas F. R. A. Prado <n@nfraprado.net> escreveu: > > > On Sat, Jun 05, 2021 at 09:08:36PM +0200, Mauro Carvalho Chehab wrote: > > > Em Sat, 5 Jun 2021 12:11:09 -0300 > > > Nícolas F. R. A. Prado <n@nfraprado.net> escreveu: > > > > > > > Hi Mauro, > > > > > > > > On Sat, Jun 05, 2021 at 03:17:59PM +0200, Mauro Carvalho Chehab wrote: > > > > > As discussed at: > > > > > https://lore.kernel.org/linux-doc/871r9k6rmy.fsf@meer.lwn.net/ > > > > > > > > > > It is better to avoid using :doc:`foo` to refer to Documentation/foo.rst, as the > > > > > automarkup.py extension should handle it automatically, on most cases. > > > > > > > > > > There are a couple of exceptions to this rule: > > > > > > > > > > 1. when :doc: tag is used to point to a kernel-doc DOC: markup; > > > > > 2. when it is used with a named tag, e. g. :doc:`some name <foo>`; > > > > > > > > > > It should also be noticed that automarkup.py has currently an issue: > > > > > if one use a markup like: > > > > > > > > > > Documentation/dev-tools/kunit/api/test.rst > > > > > - documents all of the standard testing API excluding mocking > > > > > or mocking related features. > > > > > > > > > > or, even: > > > > > > > > > > Documentation/dev-tools/kunit/api/test.rst > > > > > documents all of the standard testing API excluding mocking > > > > > or mocking related features. > > > > > > > > > > The automarkup.py will simply ignore it. Not sure why. This patch series > > > > > avoid the above patterns (which is present only on 4 files), but it would be > > > > > nice to have a followup patch fixing the issue at automarkup.py. > > > > > > > > What I think is happening here is that we're using rST's syntax for definition > > > > lists [1]. automarkup.py ignores literal nodes, and perhaps a definition is > > > > considered a literal by Sphinx. Adding a blank line after the Documentation/... > > > > or removing the additional indentation makes it work, like you did in your > > > > 2nd and 3rd patch, since then it's not a definition anymore, although then the > > > > visual output is different as well. > > > > > > A literal has a different output. I think that this is not the case, but I > > > didn't check the python code from docutils/Sphinx. > > > > Okay, I went in deeper to understand the issue and indeed it wasn't what I > > thought. The reason definitions are ignored by automarkup.py is because the main > > loop iterates only over nodes that are of type paragraph: > > > > 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)) > > > > And inspecting the HTML output from your example, the definition name is inside > > a <dt> tag, and it doesn't have a <p> inside. So in summary, automarkup.py will > > only work on elements which are inside a <p> in the output. > > > Yeah, that's what I was suspecting, based on the comments. > > Maybe something similar to the above could be done also for some > non-paragraph data. By looking at: > > https://docutils.sourceforge.io/docs/ref/doctree.html > > It says that the body elements are: > > admonition, attention, block_quote, bullet_list, caution, citation, > comment, compound, container, danger, definition_list, doctest_block, > enumerated_list, error, field_list, figure, footnote, hint, image, > important, line_block, literal_block, note, option_list, paragraph, > pending, raw, rubric, substitution_definition, system_message, > table, target, tip, warning Ok, I went through each one by searching the term on [1] and inspecting the element to see if it contained a <p> or not. The vast majority did. These are the ones I didn't find there or didn't make sense: comment container image pending raw substitution_definition system_message target We can safely ignore them. And these are the ones that matter and don't have paragraphs: 1. literal_block 2. doctest_block 3. definition_list 4. field_list 5. option_list 6. line_block 1 and 2 are literals, so we don't care about them. 3 is the one you noticed the issue with. It's worth mentioning that the definition term doesn't have a paragraph, but its definition does (as can be checked by inspecting [2]). 4 is basically the same as 3, the rst syntax is different but the output is the same. That said, I believe we only use those to set options at the top of the file, like in translations, and I can't see automarkup being useful in there. 5 is similar to 3 and 4, but the term is formatted using <kbd>, so it's like a literal and therefore not relevant. 6 is useful just to preserve indentation, and I'm pretty sure we don't use it in the docs. So in the end, I think the only contenders to be added to automarkup are definition lists, and even then I still think we should just substitute those definition lists with alternatives like you did in your patches. Personally I don't see much gain in using definitions instead of a simple paragraph. But if you really think it's an improvement in some way, it could probably be added to automarkup in the way you described. Thanks, Nícolas [1] https://sphinx-rtd-theme.readthedocs.io/en/stable/index.html [2] https://sphinx-rtd-theme.readthedocs.io/en/stable/demo/lists_tables.html?highlight=definition%20list#definition-lists > > So, perhaps a similar loop for definition_list would do the trick, > but maybe automarkup should also look at other types, like enum lists, > notes (and their variants, like error/warning) and footnotes. > > No idea how this would affect the docs build time, though. > > > Only applying the automarkup inside paragraphs seems like a good decision (which > > covers text in lists and tables as well), so unless there are other types of > > elements without paragraphs where automarkup should work, I think we should just > > avoid using definition lists pointing to documents like that. > > Checking the code or doing some tests are needed for us to be sure about what > of the above types docutils don't consider a paragraph. > > Thanks, > Mauro ^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag 2021-06-08 0:34 ` Nícolas F. R. A. Prado @ 2021-06-08 7:28 ` Mauro Carvalho Chehab 0 siblings, 0 replies; 17+ messages in thread From: Mauro Carvalho Chehab @ 2021-06-08 7:28 UTC (permalink / raw) To: Nícolas F. R. A. Prado Cc: Jonathan Corbet, Linux Doc Mailing List, linux-kernel, bpf, coresight, devicetree, kunit-dev, kvm, linux-acpi, linux-arm-kernel, linux-gpio, linux-hwmon, linux-i2c, linux-kselftest, linux-media, linux-pci, linux-pm, linux-security-module, netdev Em Mon, 7 Jun 2021 21:34:58 -0300 Nícolas F. R. A. Prado <n@nfraprado.net> escreveu: > Hi Mauro, > > On Mon, Jun 07, 2021 at 09:34:22AM +0200, Mauro Carvalho Chehab wrote: > > Em Sun, 6 Jun 2021 19:52:25 -0300 > > Nícolas F. R. A. Prado <n@nfraprado.net> escreveu: > > > > > On Sat, Jun 05, 2021 at 09:08:36PM +0200, Mauro Carvalho Chehab wrote: > > > > Em Sat, 5 Jun 2021 12:11:09 -0300 > > > > Nícolas F. R. A. Prado <n@nfraprado.net> escreveu: > > > > > > > > > Hi Mauro, > > > > > > > > > > On Sat, Jun 05, 2021 at 03:17:59PM +0200, Mauro Carvalho Chehab wrote: > > > > > > As discussed at: > > > > > > https://lore.kernel.org/linux-doc/871r9k6rmy.fsf@meer.lwn.net/ > > > > > > > > > > > > It is better to avoid using :doc:`foo` to refer to Documentation/foo.rst, as the > > > > > > automarkup.py extension should handle it automatically, on most cases. > > > > > > > > > > > > There are a couple of exceptions to this rule: > > > > > > > > > > > > 1. when :doc: tag is used to point to a kernel-doc DOC: markup; > > > > > > 2. when it is used with a named tag, e. g. :doc:`some name <foo>`; > > > > > > > > > > > > It should also be noticed that automarkup.py has currently an issue: > > > > > > if one use a markup like: > > > > > > > > > > > > Documentation/dev-tools/kunit/api/test.rst > > > > > > - documents all of the standard testing API excluding mocking > > > > > > or mocking related features. > > > > > > > > > > > > or, even: > > > > > > > > > > > > Documentation/dev-tools/kunit/api/test.rst > > > > > > documents all of the standard testing API excluding mocking > > > > > > or mocking related features. > > > > > > > > > > > > The automarkup.py will simply ignore it. Not sure why. This patch series > > > > > > avoid the above patterns (which is present only on 4 files), but it would be > > > > > > nice to have a followup patch fixing the issue at automarkup.py. > > > > > > > > > > What I think is happening here is that we're using rST's syntax for definition > > > > > lists [1]. automarkup.py ignores literal nodes, and perhaps a definition is > > > > > considered a literal by Sphinx. Adding a blank line after the Documentation/... > > > > > or removing the additional indentation makes it work, like you did in your > > > > > 2nd and 3rd patch, since then it's not a definition anymore, although then the > > > > > visual output is different as well. > > > > > > > > A literal has a different output. I think that this is not the case, but I > > > > didn't check the python code from docutils/Sphinx. > > > > > > Okay, I went in deeper to understand the issue and indeed it wasn't what I > > > thought. The reason definitions are ignored by automarkup.py is because the main > > > loop iterates only over nodes that are of type paragraph: > > > > > > 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)) > > > > > > And inspecting the HTML output from your example, the definition name is inside > > > a <dt> tag, and it doesn't have a <p> inside. So in summary, automarkup.py will > > > only work on elements which are inside a <p> in the output. > > > > > > Yeah, that's what I was suspecting, based on the comments. > > > > Maybe something similar to the above could be done also for some > > non-paragraph data. By looking at: > > > > https://docutils.sourceforge.io/docs/ref/doctree.html > > > > It says that the body elements are: > > > > admonition, attention, block_quote, bullet_list, caution, citation, > > comment, compound, container, danger, definition_list, doctest_block, > > enumerated_list, error, field_list, figure, footnote, hint, image, > > important, line_block, literal_block, note, option_list, paragraph, > > pending, raw, rubric, substitution_definition, system_message, > > table, target, tip, warning > > Ok, I went through each one by searching the term on [1] and inspecting the > element to see if it contained a <p> or not. The vast majority did. These are > the ones I didn't find there or didn't make sense: > > comment > container > image > pending > raw > substitution_definition > system_message > target > > We can safely ignore them. And these are the ones that matter and don't have > paragraphs: > > 1. literal_block > 2. doctest_block > 3. definition_list > 4. field_list > 5. option_list > 6. line_block > > 1 and 2 are literals, so we don't care about them. > > 3 is the one you noticed the issue with. It's worth mentioning that the > definition term doesn't have a paragraph, but its definition does (as can be > checked by inspecting [2]). > > 4 is basically the same as 3, the rst syntax is different but the output is the > same. That said, I believe we only use those to set options at the top of the > file, like in translations, and I can't see automarkup being useful in there. > > 5 is similar to 3 and 4, but the term is formatted using <kbd>, so it's like a > literal and therefore not relevant. > > 6 is useful just to preserve indentation, and I'm pretty sure we don't use it in > the docs. > > So in the end, I think the only contenders to be added to automarkup are > definition lists, and even then I still think we should just substitute those > definition lists with alternatives like you did in your patches. Personally I > don't see much gain in using definitions instead of a simple paragraph. But if > you really think it's an improvement in some way, it could probably be added to > automarkup in the way you described. Thank you for checking this! Kernel docs use a lot definition lists. At the initial versions, it was equivalent to: **Something to be written with emphasis** Some description Sphinx later changed the look-and-feel for the term, on html output, but the thing is that: Something to be written with emphasis Some description looks a lot better when read as a text file. Also, on some cases, the first notation doesn't work. The definition-list was the only way I know that would allow to apply an emphasis to a literal block. We can avoid using Documentation/foo on description lists: the current 4 cases where doc:`foo` are already addressed in this series, and the output is acceptable. Yet, I have a couple of concerns: 1. It might have some unknown places where a description list is used for Documentation/foo; 2. It is not trivial to identify if someone add Documentation/foo in the future; 3. I suspect that there are several places where functions and structs appear at the definition lists. (1) can probably be checked with a multi-line grep. So, not a big problem; (2) is something that would require someone to verify from time to time; but (3) are harder to check and seems to be a valid use-case. Due to (3), I think we should let automarkup to parse non-literal terms on description lists. At very least it should emit a warning when it won't be doing auto-conversions for known patterns at definition lists (if doing that would generate false-positives). Thanks, Mauro ^ permalink raw reply [flat|nested] 17+ messages in thread
end of thread, other threads:[~2021-06-16 6:13 UTC | newest] Thread overview: 17+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2021-06-05 13:17 [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag Mauro Carvalho Chehab 2021-06-05 13:18 ` [PATCH 02/34] docs: dev-tools: kunit: don't use a table for docs name Mauro Carvalho Chehab 2021-06-05 15:43 ` David Gow 2021-06-05 16:06 ` Mauro Carvalho Chehab 2021-06-07 20:14 ` Brendan Higgins 2021-06-05 13:18 ` [PATCH 14/34] docs: dev-tools: kunit: avoid using ReST :doc:`foo` markup Mauro Carvalho Chehab 2021-06-05 15:44 ` David Gow 2021-06-16 6:00 ` Mauro Carvalho Chehab 2021-06-16 6:13 ` Mauro Carvalho Chehab 2021-06-07 20:20 ` Brendan Higgins 2021-06-05 13:37 ` [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag Mauro Carvalho Chehab 2021-06-05 15:11 ` Nícolas F. R. A. Prado 2021-06-05 19:08 ` Mauro Carvalho Chehab 2021-06-06 22:52 ` Nícolas F. R. A. Prado 2021-06-07 7:34 ` Mauro Carvalho Chehab 2021-06-08 0:34 ` Nícolas F. R. A. Prado 2021-06-08 7:28 ` Mauro Carvalho Chehab
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).