* [PATCH v2 00/29] docs: avoid using ReST :doc:`foo` tag
@ 2021-06-16 6:27 Mauro Carvalho Chehab
2021-06-16 6:27 ` [PATCH v2 25/29] docs: trace: coresight: coresight.rst: avoid using ReST :doc:`foo` markup Mauro Carvalho Chehab
2021-06-17 19:34 ` [PATCH v2 00/29] docs: avoid using ReST :doc:`foo` tag Jonathan Corbet
0 siblings, 2 replies; 4+ messages in thread
From: Mauro Carvalho Chehab @ 2021-06-16 6:27 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-i2c, linux-kselftest, linux-pci, linux-pm,
linux-security-module, netdev, x86
(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(-)
--
2.31.1
_______________________________________________
linux-arm-kernel mailing list
linux-arm-kernel@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel
^ permalink raw reply [flat|nested] 4+ messages in thread
* [PATCH v2 25/29] docs: trace: coresight: coresight.rst: avoid using ReST :doc:`foo` markup
2021-06-16 6:27 [PATCH v2 00/29] docs: avoid using ReST :doc:`foo` tag Mauro Carvalho Chehab
@ 2021-06-16 6:27 ` Mauro Carvalho Chehab
2021-06-17 15:03 ` Mathieu Poirier
2021-06-17 19:34 ` [PATCH v2 00/29] docs: avoid using ReST :doc:`foo` tag Jonathan Corbet
1 sibling, 1 reply; 4+ messages in thread
From: Mauro Carvalho Chehab @ 2021-06-16 6:27 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Leo Yan, Mathieu Poirier, Mike Leach,
Suzuki K Poulose, coresight, linux-arm-kernel, linux-kernel
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/trace/coresight/coresight.rst | 8 +++++---
1 file changed, 5 insertions(+), 3 deletions(-)
diff --git a/Documentation/trace/coresight/coresight.rst b/Documentation/trace/coresight/coresight.rst
index 169749efd8d1..1ec8dc35b1d8 100644
--- a/Documentation/trace/coresight/coresight.rst
+++ b/Documentation/trace/coresight/coresight.rst
@@ -315,7 +315,8 @@ intermediate links as required.
Note: ``cti_sys0`` appears in two of the connections lists above.
CTIs can connect to multiple devices and are arranged in a star topology
-via the CTM. See (:doc:`coresight-ect`) [#fourth]_ for further details.
+via the CTM. See (Documentation/trace/coresight/coresight-ect.rst)
+[#fourth]_ for further details.
Looking at this device we see 4 connections::
linaro-developer:~# ls -l /sys/bus/coresight/devices/cti_sys0/connections
@@ -606,7 +607,8 @@ interface provided for that purpose by the generic STM API::
crw------- 1 root root 10, 61 Jan 3 18:11 /dev/stm0
root@genericarmv8:~#
-Details on how to use the generic STM API can be found here:- :doc:`../stm` [#second]_.
+Details on how to use the generic STM API can be found here:
+- Documentation/trace/stm.rst [#second]_.
The CTI & CTM Modules
---------------------
@@ -616,7 +618,7 @@ individual CTIs and components, and can propagate these between all CTIs via
channels on the CTM (Cross Trigger Matrix).
A separate documentation file is provided to explain the use of these devices.
-(:doc:`coresight-ect`) [#fourth]_.
+(Documentation/trace/coresight/coresight-ect.rst) [#fourth]_.
.. [#first] Documentation/ABI/testing/sysfs-bus-coresight-devices-stm
--
2.31.1
_______________________________________________
linux-arm-kernel mailing list
linux-arm-kernel@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel
^ permalink raw reply related [flat|nested] 4+ messages in thread
* Re: [PATCH v2 25/29] docs: trace: coresight: coresight.rst: avoid using ReST :doc:`foo` markup
2021-06-16 6:27 ` [PATCH v2 25/29] docs: trace: coresight: coresight.rst: avoid using ReST :doc:`foo` markup Mauro Carvalho Chehab
@ 2021-06-17 15:03 ` Mathieu Poirier
0 siblings, 0 replies; 4+ messages in thread
From: Mathieu Poirier @ 2021-06-17 15:03 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Jonathan Corbet, Linux Doc Mailing List, Leo Yan, Mike Leach,
Suzuki K Poulose, coresight, linux-arm-kernel, linux-kernel
On Wed, Jun 16, 2021 at 08:27:40AM +0200, Mauro Carvalho Chehab 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>
> ---
> Documentation/trace/coresight/coresight.rst | 8 +++++---
> 1 file changed, 5 insertions(+), 3 deletions(-)
>
Reviewed-by: Mathieu Poirier <mathieu.poirier@linaro.org>
> diff --git a/Documentation/trace/coresight/coresight.rst b/Documentation/trace/coresight/coresight.rst
> index 169749efd8d1..1ec8dc35b1d8 100644
> --- a/Documentation/trace/coresight/coresight.rst
> +++ b/Documentation/trace/coresight/coresight.rst
> @@ -315,7 +315,8 @@ intermediate links as required.
>
> Note: ``cti_sys0`` appears in two of the connections lists above.
> CTIs can connect to multiple devices and are arranged in a star topology
> -via the CTM. See (:doc:`coresight-ect`) [#fourth]_ for further details.
> +via the CTM. See (Documentation/trace/coresight/coresight-ect.rst)
> +[#fourth]_ for further details.
> Looking at this device we see 4 connections::
>
> linaro-developer:~# ls -l /sys/bus/coresight/devices/cti_sys0/connections
> @@ -606,7 +607,8 @@ interface provided for that purpose by the generic STM API::
> crw------- 1 root root 10, 61 Jan 3 18:11 /dev/stm0
> root@genericarmv8:~#
>
> -Details on how to use the generic STM API can be found here:- :doc:`../stm` [#second]_.
> +Details on how to use the generic STM API can be found here:
> +- Documentation/trace/stm.rst [#second]_.
>
> The CTI & CTM Modules
> ---------------------
> @@ -616,7 +618,7 @@ individual CTIs and components, and can propagate these between all CTIs via
> channels on the CTM (Cross Trigger Matrix).
>
> A separate documentation file is provided to explain the use of these devices.
> -(:doc:`coresight-ect`) [#fourth]_.
> +(Documentation/trace/coresight/coresight-ect.rst) [#fourth]_.
>
>
> .. [#first] Documentation/ABI/testing/sysfs-bus-coresight-devices-stm
> --
> 2.31.1
>
_______________________________________________
linux-arm-kernel mailing list
linux-arm-kernel@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [PATCH v2 00/29] docs: avoid using ReST :doc:`foo` tag
2021-06-16 6:27 [PATCH v2 00/29] docs: avoid using ReST :doc:`foo` tag Mauro Carvalho Chehab
2021-06-16 6:27 ` [PATCH v2 25/29] docs: trace: coresight: coresight.rst: avoid using ReST :doc:`foo` markup Mauro Carvalho Chehab
@ 2021-06-17 19:34 ` Jonathan Corbet
1 sibling, 0 replies; 4+ messages in thread
From: Jonathan Corbet @ 2021-06-17 19:34 UTC (permalink / raw)
To: Mauro Carvalho Chehab, Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, linux-kernel, bpf, coresight, devicetree,
kunit-dev, kvm, linux-acpi, linux-arm-kernel, linux-gpio,
linux-i2c, linux-kselftest, linux-pci, linux-pm,
linux-security-module, netdev, x86
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-arm-kernel mailing list
linux-arm-kernel@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel
^ permalink raw reply [flat|nested] 4+ messages in thread
end of thread, other threads:[~2021-06-17 19:37 UTC | newest]
Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-06-16 6:27 [PATCH v2 00/29] docs: avoid using ReST :doc:`foo` tag Mauro Carvalho Chehab
2021-06-16 6:27 ` [PATCH v2 25/29] docs: trace: coresight: coresight.rst: avoid using ReST :doc:`foo` markup Mauro Carvalho Chehab
2021-06-17 15:03 ` Mathieu Poirier
2021-06-17 19:34 ` [PATCH v2 00/29] docs: avoid using ReST :doc:`foo` tag Jonathan Corbet
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).