(Maintainers bcc, to avoid too many recipient troubles)
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>`;
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
The remaining patches convert the other occurrences via a replace script. They were manually edited, in order to honour 80-columns where possible.
This series based on docs-next branch. In order to avoid merge conflicts, I rebased it internally against yesterday's linux-next, dropping a patch and a hunk that would have caused conflicts there.
I'll re-send the remaining patch (plus another patch) with conflicting changes, together with any other doc:`filename` reference that might still be upstream by 5.14-rc1.
---
v2: - dropped media patches (as I merged via my own tree); - removed one patch that would conflict at linux-next (adm1177.rst); - removed one hunk fron kunit patch that would also conflict at linux-next.
Mauro Carvalho Chehab (29): docs: devices.rst: better reference documentation docs docs: dev-tools: kunit: don't use a table for docs name 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: 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/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 | 4 +- 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 +- 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/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 +++--- Documentation/virt/kvm/s390-pv-boot.rst | 2 +- Documentation/x86/boot.rst | 4 +- Documentation/x86/mtrr.rst | 2 +- 46 files changed, 171 insertions(+), 147 deletions(-)
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.
Reviewed-by: David Gow davidgow@google.com Acked-by: Brendan Higgins brendanhiggins@google.com 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.
The :doc:`foo` tag is auto-generated via automarkup.py. So, use the filename at the sources, instead of :doc:`foo`.
Reviewed-by: David Gow davidgow@google.com Acked-by: Brendan Higgins brendanhiggins@google.com 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 | 4 ++-- Documentation/dev-tools/kunit/tips.rst | 5 +++-- Documentation/dev-tools/kunit/usage.rst | 8 +++++--- 5 files changed, 18 insertions(+), 15 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..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..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 ===============
On Tue, Jun 15, 2021 at 11:27 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`.
Reviewed-by: David Gow davidgow@google.com Acked-by: Brendan Higgins brendanhiggins@google.com Signed-off-by: Mauro Carvalho Chehab mchehab+huawei@kernel.org
Hi, can you please rebase and resend your patch on top of
https://git.kernel.org/pub/scm/linux/kernel/git/shuah/linux-kselftest.git/lo...
Brendan Higgins brendanhiggins@google.com writes:
On Tue, Jun 15, 2021 at 11:27 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`.
Reviewed-by: David Gow davidgow@google.com Acked-by: Brendan Higgins brendanhiggins@google.com Signed-off-by: Mauro Carvalho Chehab mchehab+huawei@kernel.org
Hi, can you please rebase and resend your patch on top of
https://git.kernel.org/pub/scm/linux/kernel/git/shuah/linux-kselftest.git/lo...
I applied the whole set a couple of weeks ago, actually, so there shouldn't be any need for this...
Thanks,
jon
Mauro Carvalho Chehab mchehab+huawei@kernel.org writes:
(Maintainers bcc, to avoid too many recipient troubles)
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.
I've applied the set, thanks.
jon
linux-kselftest-mirror@lists.linaro.org
-
Brendan Higgins -
Jonathan Corbet -
Mauro Carvalho Chehab