linux-kernel.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
* [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag
@ 2021-06-05 13:17 Mauro Carvalho Chehab
  2021-06-05 13:18 ` [PATCH 01/34] docs: devices.rst: better reference documentation docs Mauro Carvalho Chehab
                   ` (35 more replies)
  0 siblings, 36 replies; 63+ 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] 63+ messages in thread

* [PATCH 01/34] docs: devices.rst: better reference documentation docs
  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 13:18 ` [PATCH 02/34] docs: dev-tools: kunit: don't use a table for docs name Mauro Carvalho Chehab
                   ` (34 subsequent siblings)
  35 siblings, 0 replies; 63+ 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, linux-kernel

There's no need to use either :file: or :doc: tags for documentation,
as automarkup.py automatically converts Documentation/*.rst into
a cross-reference.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/driver-api/pm/devices.rst | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/driver-api/pm/devices.rst b/Documentation/driver-api/pm/devices.rst
index 6b3bfd29fd84..d448cb57df86 100644
--- a/Documentation/driver-api/pm/devices.rst
+++ b/Documentation/driver-api/pm/devices.rst
@@ -217,7 +217,7 @@ system-wide transition to a sleep state even though its :c:member:`runtime_auto`
 flag is clear.
 
 For more information about the runtime power management framework, refer to
-:file:`Documentation/power/runtime_pm.rst`.
+Documentation/power/runtime_pm.rst.
 
 
 Calling Drivers to Enter and Leave System Sleep States
@@ -655,7 +655,7 @@ been thawed.  Generally speaking, the PM notifiers are suitable for performing
 actions that either require user space to be available, or at least won't
 interfere with user space.
 
-For details refer to :doc:`notifiers`.
+For details refer to Documentation/driver-api/pm/notifiers.rst.
 
 
 Device Low-Power (suspend) States
@@ -726,7 +726,7 @@ it into account in any way.
 
 Devices may be defined as IRQ-safe which indicates to the PM core that their
 runtime PM callbacks may be invoked with disabled interrupts (see
-:file:`Documentation/power/runtime_pm.rst` for more information).  If an
+Documentation/power/runtime_pm.rst for more information).  If an
 IRQ-safe device belongs to a PM domain, the runtime PM of the domain will be
 disallowed, unless the domain itself is defined as IRQ-safe. However, it
 makes sense to define a PM domain as IRQ-safe only if all the devices in it
@@ -805,7 +805,7 @@ The ``DPM_FLAG_MAY_SKIP_RESUME`` Driver Flag
 --------------------------------------------
 
 During system-wide resume from a sleep state it's easiest to put devices into
-the full-power state, as explained in :file:`Documentation/power/runtime_pm.rst`.
+the full-power state, as explained in Documentation/power/runtime_pm.rst.
 [Refer to that document for more information regarding this particular issue as
 well as for information on the device runtime power management framework in
 general.]  However, it often is desirable to leave devices in suspend after
-- 
2.31.1


^ permalink raw reply related	[flat|nested] 63+ 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 ` [PATCH 01/34] docs: devices.rst: better reference documentation docs 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 03/34] media: docs: */media/index.rst: don't use ReST doc:`foo` Mauro Carvalho Chehab
                   ` (33 subsequent siblings)
  35 siblings, 2 replies; 63+ 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] 63+ messages in thread

* [PATCH 03/34] media: docs: */media/index.rst: don't use ReST doc:`foo`
  2021-06-05 13:17 [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag Mauro Carvalho Chehab
  2021-06-05 13:18 ` [PATCH 01/34] docs: devices.rst: better reference documentation docs 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 13:18 ` [PATCH 04/34] media: userspace-api: avoid using ReST :doc:`foo` markup Mauro Carvalho Chehab
                   ` (32 subsequent siblings)
  35 siblings, 0 replies; 63+ 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, Mauro Carvalho Chehab, linux-kernel, linux-media

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/admin-guide/media/index.rst   | 12 +++++++-----
 Documentation/driver-api/media/index.rst    | 10 ++++++----
 Documentation/userspace-api/media/index.rst | 12 +++++++-----
 3 files changed, 20 insertions(+), 14 deletions(-)

diff --git a/Documentation/admin-guide/media/index.rst b/Documentation/admin-guide/media/index.rst
index 6e0d2bae7154..c676af665111 100644
--- a/Documentation/admin-guide/media/index.rst
+++ b/Documentation/admin-guide/media/index.rst
@@ -11,12 +11,14 @@ its supported drivers.
 
 Please see:
 
-- :doc:`/userspace-api/media/index`
-     for the userspace APIs used on media devices.
+Documentation/userspace-api/media/index.rst
 
-- :doc:`/driver-api/media/index`
-     for driver development information and Kernel APIs used by
-     media devices;
+  - for the userspace APIs used on media devices.
+
+Documentation/driver-api/media/index.rst
+
+  - for driver development information and Kernel APIs used by
+    media devices;
 
 The media subsystem
 ===================
diff --git a/Documentation/driver-api/media/index.rst b/Documentation/driver-api/media/index.rst
index 2ad71dfa8828..813d7db59da7 100644
--- a/Documentation/driver-api/media/index.rst
+++ b/Documentation/driver-api/media/index.rst
@@ -11,11 +11,13 @@ its supported drivers.
 
 Please see:
 
-- :doc:`/admin-guide/media/index`
-    for usage information about media subsystem and supported drivers;
+Documentation/admin-guide/media/index.rst
 
-- :doc:`/userspace-api/media/index`
-     for the userspace APIs used on media devices.
+  - for usage information about media subsystem and supported drivers;
+
+Documentation/userspace-api/media/index.rst
+
+  - for the userspace APIs used on media devices.
 
 
 .. only:: html
diff --git a/Documentation/userspace-api/media/index.rst b/Documentation/userspace-api/media/index.rst
index 7f42f83b9f59..d839904be085 100644
--- a/Documentation/userspace-api/media/index.rst
+++ b/Documentation/userspace-api/media/index.rst
@@ -11,12 +11,14 @@ used by media devices.
 
 Please see:
 
-- :doc:`/admin-guide/media/index`
-    for usage information about media subsystem and supported drivers;
+Documentation/admin-guide/media/index.rst
 
-- :doc:`/driver-api/media/index`
-     for driver development information and Kernel APIs used by
-     media devices;
+  - for usage information about media subsystem and supported drivers;
+
+Documentation/driver-api/media/index.rst
+
+  - for driver development information and Kernel APIs used by
+    media devices;
 
 
 .. only:: html
-- 
2.31.1


^ permalink raw reply related	[flat|nested] 63+ messages in thread

* [PATCH 04/34] media: userspace-api: avoid using ReST :doc:`foo` markup
  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:18 ` [PATCH 03/34] media: docs: */media/index.rst: don't use ReST doc:`foo` Mauro Carvalho Chehab
@ 2021-06-05 13:18 ` Mauro Carvalho Chehab
  2021-06-05 13:18 ` [PATCH 05/34] media: driver-api: drivers: " Mauro Carvalho Chehab
                   ` (31 subsequent siblings)
  35 siblings, 0 replies; 63+ 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, Mauro Carvalho Chehab, linux-kernel, linux-media

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/userspace-api/media/glossary.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/userspace-api/media/glossary.rst b/Documentation/userspace-api/media/glossary.rst
index cb165d7176b7..96a360edbf3b 100644
--- a/Documentation/userspace-api/media/glossary.rst
+++ b/Documentation/userspace-api/media/glossary.rst
@@ -116,7 +116,7 @@ Glossary
 	  - :term:`RC API`; and
 	  - :term:`V4L2 API`.
 
-	See :doc:`index`.
+	See Documentation/userspace-api/media/index.rst.
 
     MC API
 	**Media Controller API**
-- 
2.31.1


^ permalink raw reply related	[flat|nested] 63+ messages in thread

* [PATCH 05/34] media: driver-api: drivers: avoid using ReST :doc:`foo` markup
  2021-06-05 13:17 [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag Mauro Carvalho Chehab
                   ` (3 preceding siblings ...)
  2021-06-05 13:18 ` [PATCH 04/34] media: userspace-api: avoid using ReST :doc:`foo` markup Mauro Carvalho Chehab
@ 2021-06-05 13:18 ` Mauro Carvalho Chehab
  2021-06-05 13:18 ` [PATCH 06/34] media: admin-guide: " Mauro Carvalho Chehab
                   ` (30 subsequent siblings)
  35 siblings, 0 replies; 63+ 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, Mauro Carvalho Chehab, linux-kernel, linux-media

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/driver-api/media/drivers/bttv-devel.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/driver-api/media/drivers/bttv-devel.rst b/Documentation/driver-api/media/drivers/bttv-devel.rst
index c9aa8b95a5e5..0885a04563a9 100644
--- a/Documentation/driver-api/media/drivers/bttv-devel.rst
+++ b/Documentation/driver-api/media/drivers/bttv-devel.rst
@@ -21,7 +21,7 @@ log, telling which card type is used.  Like this one::
 
 You should verify this is correct.  If it isn't, you have to pass the
 correct board type as insmod argument, ``insmod bttv card=2`` for
-example.  The file :doc:`/admin-guide/media/bttv-cardlist` has a list
+example.  The file Documentation/admin-guide/media/bttv-cardlist.rst has a list
 of valid arguments for card.
 
 If your card isn't listed there, you might check the source code for
-- 
2.31.1


^ permalink raw reply related	[flat|nested] 63+ messages in thread

* [PATCH 06/34] media: admin-guide: avoid using ReST :doc:`foo` markup
  2021-06-05 13:17 [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag Mauro Carvalho Chehab
                   ` (4 preceding siblings ...)
  2021-06-05 13:18 ` [PATCH 05/34] media: driver-api: drivers: " Mauro Carvalho Chehab
@ 2021-06-05 13:18 ` Mauro Carvalho Chehab
  2021-06-05 13:18 ` [PATCH 07/34] docs: admin-guide: pm: avoid using ReSt " Mauro Carvalho Chehab
                   ` (29 subsequent siblings)
  35 siblings, 0 replies; 63+ 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, Mauro Carvalho Chehab, linux-kernel, linux-media

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/admin-guide/media/bt8xx.rst   | 15 ++++++++-------
 Documentation/admin-guide/media/bttv.rst    | 21 +++++++++++----------
 Documentation/admin-guide/media/saa7134.rst |  3 ++-
 3 files changed, 21 insertions(+), 18 deletions(-)

diff --git a/Documentation/admin-guide/media/bt8xx.rst b/Documentation/admin-guide/media/bt8xx.rst
index 1382ada1e38e..3589f6ab7e46 100644
--- a/Documentation/admin-guide/media/bt8xx.rst
+++ b/Documentation/admin-guide/media/bt8xx.rst
@@ -15,11 +15,12 @@ Authors:
 General information
 -------------------
 
-This class of cards has a bt878a as the PCI interface, and require the bttv driver
-for accessing the i2c bus and the gpio pins of the bt8xx chipset.
+This class of cards has a bt878a as the PCI interface, and require the bttv
+driver for accessing the i2c bus and the gpio pins of the bt8xx chipset.
 
-Please see :doc:`bttv-cardlist` for a complete list of Cards based on the
-Conexant Bt8xx PCI bridge supported by the Linux Kernel.
+Please see Documentation/admin-guide/media/bttv-cardlist.rst for a complete
+list of Cards based on the Conexant Bt8xx PCI bridge supported by the
+Linux Kernel.
 
 In order to be able to compile the kernel, some config options should be
 enabled::
@@ -80,7 +81,7 @@ for dvb-bt8xx drivers by passing modprobe parameters may be necessary.
 Running TwinHan and Clones
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-As shown at :doc:`bttv-cardlist`, TwinHan and
+As shown at Documentation/admin-guide/media/bttv-cardlist.rst, TwinHan and
 clones use ``card=113`` modprobe parameter. So, in order to properly
 detect it for devices without EEPROM, you should use::
 
@@ -105,12 +106,12 @@ The autodetected values are determined by the cards' "response string".
 In your logs see f. ex.: dst_get_device_id: Recognize [DSTMCI].
 
 For bug reports please send in a complete log with verbose=4 activated.
-Please also see :doc:`ci`.
+Please also see Documentation/admin-guide/media/ci.rst.
 
 Running multiple cards
 ~~~~~~~~~~~~~~~~~~~~~~
 
-See :doc:`bttv-cardlist` for a complete list of
+See Documentation/admin-guide/media/bttv-cardlist.rst for a complete list of
 Card ID. Some examples:
 
 	===========================	===
diff --git a/Documentation/admin-guide/media/bttv.rst b/Documentation/admin-guide/media/bttv.rst
index 0ef1f203104d..125f6f47123d 100644
--- a/Documentation/admin-guide/media/bttv.rst
+++ b/Documentation/admin-guide/media/bttv.rst
@@ -24,7 +24,8 @@ If your board has digital TV, you'll also need::
 
     ./scripts/config -m DVB_BT8XX
 
-In this case, please see :doc:`bt8xx` for additional notes.
+In this case, please see Documentation/admin-guide/media/bt8xx.rst
+for additional notes.
 
 Make bttv work with your card
 -----------------------------
@@ -39,7 +40,7 @@ If it doesn't bttv likely could not autodetect your card and needs some
 insmod options.  The most important insmod option for bttv is "card=n"
 to select the correct card type.  If you get video but no sound you've
 very likely specified the wrong (or no) card type.  A list of supported
-cards is in :doc:`bttv-cardlist`.
+cards is in Documentation/admin-guide/media/bttv-cardlist.rst.
 
 If bttv takes very long to load (happens sometimes with the cheap
 cards which have no tuner), try adding this to your modules configuration
@@ -57,8 +58,8 @@ directory should be enough for it to be autoload during the driver's
 probing mode (e. g. when the Kernel boots or when the driver is
 manually loaded via ``modprobe`` command).
 
-If your card isn't listed in :doc:`bttv-cardlist` or if you have
-trouble making audio work, please read :ref:`still_doesnt_work`.
+If your card isn't listed in Documentation/admin-guide/media/bttv-cardlist.rst
+or if you have trouble making audio work, please read :ref:`still_doesnt_work`.
 
 
 Autodetecting cards
@@ -77,8 +78,8 @@ the Subsystem ID in the second line, looks like this:
 only bt878-based cards can have a subsystem ID (which does not mean
 that every card really has one).  bt848 cards can't have a Subsystem
 ID and therefore can't be autodetected.  There is a list with the ID's
-at :doc:`bttv-cardlist` (in case you are interested or want to mail
-patches with updates).
+at Documentation/admin-guide/media/bttv-cardlist.rst
+(in case you are interested or want to mail patches with updates).
 
 
 .. _still_doesnt_work:
@@ -259,15 +260,15 @@ bug.  It is very helpful if you can tell where exactly it broke
 With a hard freeze you probably doesn't find anything in the logfiles.
 The only way to capture any kernel messages is to hook up a serial
 console and let some terminal application log the messages.  /me uses
-screen.  See :doc:`/admin-guide/serial-console` for details on setting
-up a serial console.
+screen.  See Documentation/admin-guide/serial-console.rst for details on
+setting up a serial console.
 
-Read :doc:`/admin-guide/bug-hunting` to learn how to get any useful
+Read Documentation/admin-guide/bug-hunting.rst to learn how to get any useful
 information out of a register+stack dump printed by the kernel on
 protection faults (so-called "kernel oops").
 
 If you run into some kind of deadlock, you can try to dump a call trace
-for each process using sysrq-t (see :doc:`/admin-guide/sysrq`).
+for each process using sysrq-t (see Documentation/admin-guide/sysrq.rst).
 This way it is possible to figure where *exactly* some process in "D"
 state is stuck.
 
diff --git a/Documentation/admin-guide/media/saa7134.rst b/Documentation/admin-guide/media/saa7134.rst
index 7ab9c70b9abe..51eae7eb5ab7 100644
--- a/Documentation/admin-guide/media/saa7134.rst
+++ b/Documentation/admin-guide/media/saa7134.rst
@@ -50,7 +50,8 @@ To build and install, you should run::
 Once the new Kernel is booted, saa7134 driver should be loaded automatically.
 
 Depending on the card you might have to pass ``card=<nr>`` as insmod option.
-If so, please check :doc:`saa7134-cardlist` for valid choices.
+If so, please check Documentation/admin-guide/media/saa7134-cardlist.rst
+for valid choices.
 
 Once you have your card type number, you can pass a modules configuration
 via a file (usually, it is either ``/etc/modules.conf`` or some file at
-- 
2.31.1


^ permalink raw reply related	[flat|nested] 63+ messages in thread

* [PATCH 07/34] docs: admin-guide: pm: avoid using ReSt :doc:`foo` markup
  2021-06-05 13:17 [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag Mauro Carvalho Chehab
                   ` (5 preceding siblings ...)
  2021-06-05 13:18 ` [PATCH 06/34] media: admin-guide: " Mauro Carvalho Chehab
@ 2021-06-05 13:18 ` Mauro Carvalho Chehab
  2021-06-05 13:18 ` [PATCH 08/34] docs: admin-guide: hw-vuln: avoid using ReST " Mauro Carvalho Chehab
                   ` (28 subsequent siblings)
  35 siblings, 0 replies; 63+ 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, Rafael J. Wysocki, Viresh Kumar,
	linux-kernel, linux-pm

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/admin-guide/pm/intel_idle.rst   | 16 ++++++++++------
 Documentation/admin-guide/pm/intel_pstate.rst |  9 +++++----
 2 files changed, 15 insertions(+), 10 deletions(-)

diff --git a/Documentation/admin-guide/pm/intel_idle.rst b/Documentation/admin-guide/pm/intel_idle.rst
index 89309e1b0e48..b799a43da62e 100644
--- a/Documentation/admin-guide/pm/intel_idle.rst
+++ b/Documentation/admin-guide/pm/intel_idle.rst
@@ -20,8 +20,8 @@ Nehalem and later generations of Intel processors, but the level of support for
 a particular processor model in it depends on whether or not it recognizes that
 processor model and may also depend on information coming from the platform
 firmware.  [To understand ``intel_idle`` it is necessary to know how ``CPUIdle``
-works in general, so this is the time to get familiar with :doc:`cpuidle` if you
-have not done that yet.]
+works in general, so this is the time to get familiar with
+Documentation/admin-guide/pm/cpuidle.rst if you have not done that yet.]
 
 ``intel_idle`` uses the ``MWAIT`` instruction to inform the processor that the
 logical CPU executing it is idle and so it may be possible to put some of the
@@ -53,7 +53,8 @@ processor) corresponding to them depends on the processor model and it may also
 depend on the configuration of the platform.
 
 In order to create a list of available idle states required by the ``CPUIdle``
-subsystem (see :ref:`idle-states-representation` in :doc:`cpuidle`),
+subsystem (see :ref:`idle-states-representation` in
+Documentation/admin-guide/pm/cpuidle.rst),
 ``intel_idle`` can use two sources of information: static tables of idle states
 for different processor models included in the driver itself and the ACPI tables
 of the system.  The former are always used if the processor model at hand is
@@ -98,7 +99,8 @@ states may not be enabled by default if there are no matching entries in the
 preliminary list of idle states coming from the ACPI tables.  In that case user
 space still can enable them later (on a per-CPU basis) with the help of
 the ``disable`` idle state attribute in ``sysfs`` (see
-:ref:`idle-states-representation` in :doc:`cpuidle`).  This basically means that
+:ref:`idle-states-representation` in
+Documentation/admin-guide/pm/cpuidle.rst).  This basically means that
 the idle states "known" to the driver may not be enabled by default if they have
 not been exposed by the platform firmware (through the ACPI tables).
 
@@ -186,7 +188,8 @@ be desirable.  In practice, it is only really necessary to do that if the idle
 states in question cannot be enabled during system startup, because in the
 working state of the system the CPU power management quality of service (PM
 QoS) feature can be used to prevent ``CPUIdle`` from touching those idle states
-even if they have been enumerated (see :ref:`cpu-pm-qos` in :doc:`cpuidle`).
+even if they have been enumerated (see :ref:`cpu-pm-qos` in
+Documentation/admin-guide/pm/cpuidle.rst).
 Setting ``max_cstate`` to 0 causes the ``intel_idle`` initialization to fail.
 
 The ``no_acpi`` and ``use_acpi`` module parameters (recognized by ``intel_idle``
@@ -202,7 +205,8 @@ Namely, the positions of the bits that are set in the ``states_off`` value are
 the indices of idle states to be disabled by default (as reflected by the names
 of the corresponding idle state directories in ``sysfs``, :file:`state0`,
 :file:`state1` ... :file:`state<i>` ..., where ``<i>`` is the index of the given
-idle state; see :ref:`idle-states-representation` in :doc:`cpuidle`).
+idle state; see :ref:`idle-states-representation` in
+Documentation/admin-guide/pm/cpuidle.rst).
 
 For example, if ``states_off`` is equal to 3, the driver will disable idle
 states 0 and 1 by default, and if it is equal to 8, idle state 3 will be
diff --git a/Documentation/admin-guide/pm/intel_pstate.rst b/Documentation/admin-guide/pm/intel_pstate.rst
index df29b4f1f219..7a7d4b041eac 100644
--- a/Documentation/admin-guide/pm/intel_pstate.rst
+++ b/Documentation/admin-guide/pm/intel_pstate.rst
@@ -18,8 +18,8 @@ General Information
 (``CPUFreq``).  It is a scaling driver for the Sandy Bridge and later
 generations of Intel processors.  Note, however, that some of those processors
 may not be supported.  [To understand ``intel_pstate`` it is necessary to know
-how ``CPUFreq`` works in general, so this is the time to read :doc:`cpufreq` if
-you have not done that yet.]
+how ``CPUFreq`` works in general, so this is the time to read
+Documentation/admin-guide/pm/cpufreq.rst if you have not done that yet.]
 
 For the processors supported by ``intel_pstate``, the P-state concept is broader
 than just an operating frequency or an operating performance point (see the
@@ -445,8 +445,9 @@ Interpretation of Policy Attributes
 -----------------------------------
 
 The interpretation of some ``CPUFreq`` policy attributes described in
-:doc:`cpufreq` is special with ``intel_pstate`` as the current scaling driver
-and it generally depends on the driver's `operation mode <Operation Modes_>`_.
+Documentation/admin-guide/pm/cpufreq.rst is special with ``intel_pstate``
+as the current scaling driver and it generally depends on the driver's
+`operation mode <Operation Modes_>`_.
 
 First of all, the values of the ``cpuinfo_max_freq``, ``cpuinfo_min_freq`` and
 ``scaling_cur_freq`` attributes are produced by applying a processor-specific
-- 
2.31.1


^ permalink raw reply related	[flat|nested] 63+ messages in thread

* [PATCH 08/34] docs: admin-guide: hw-vuln: avoid using ReST :doc:`foo` markup
  2021-06-05 13:17 [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag Mauro Carvalho Chehab
                   ` (6 preceding siblings ...)
  2021-06-05 13:18 ` [PATCH 07/34] docs: admin-guide: pm: avoid using ReSt " Mauro Carvalho Chehab
@ 2021-06-05 13:18 ` Mauro Carvalho Chehab
  2021-06-05 13:18 ` [PATCH 09/34] docs: admin-guide: sysctl: " Mauro Carvalho Chehab
                   ` (27 subsequent siblings)
  35 siblings, 0 replies; 63+ 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, Heinrich Schuchardt, Mark Gross, 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>
---
 .../hw-vuln/special-register-buffer-data-sampling.rst          | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/admin-guide/hw-vuln/special-register-buffer-data-sampling.rst b/Documentation/admin-guide/hw-vuln/special-register-buffer-data-sampling.rst
index 3b1ce68d2456..966c9b3296ea 100644
--- a/Documentation/admin-guide/hw-vuln/special-register-buffer-data-sampling.rst
+++ b/Documentation/admin-guide/hw-vuln/special-register-buffer-data-sampling.rst
@@ -3,7 +3,8 @@
 SRBDS - Special Register Buffer Data Sampling
 =============================================
 
-SRBDS is a hardware vulnerability that allows MDS :doc:`mds` techniques to
+SRBDS is a hardware vulnerability that allows MDS
+Documentation/admin-guide/hw-vuln/mds.rst techniques to
 infer values returned from special register accesses.  Special register
 accesses are accesses to off core registers.  According to Intel's evaluation,
 the special register reads that have a security expectation of privacy are
-- 
2.31.1


^ permalink raw reply related	[flat|nested] 63+ messages in thread

* [PATCH 09/34] docs: admin-guide: sysctl: avoid using ReST :doc:`foo` markup
  2021-06-05 13:17 [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag Mauro Carvalho Chehab
                   ` (7 preceding siblings ...)
  2021-06-05 13:18 ` [PATCH 08/34] docs: admin-guide: hw-vuln: avoid using ReST " Mauro Carvalho Chehab
@ 2021-06-05 13:18 ` Mauro Carvalho Chehab
  2021-06-05 13:18 ` [PATCH 10/34] docs: block: biodoc.rst: avoid using ReSt " Mauro Carvalho Chehab
                   ` (26 subsequent siblings)
  35 siblings, 0 replies; 63+ 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, Guilherme G. Piccoli, Andrew Klychkov,
	Andrew Morton, Mathieu Chouquet-Stringer, Qais Yousef,
	Randy Dunlap, Stephen Kitt, 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/admin-guide/sysctl/abi.rst    |  2 +-
 Documentation/admin-guide/sysctl/kernel.rst | 37 +++++++++++----------
 2 files changed, 21 insertions(+), 18 deletions(-)

diff --git a/Documentation/admin-guide/sysctl/abi.rst b/Documentation/admin-guide/sysctl/abi.rst
index 77b1d1b2ad42..4e6db0a2a4c0 100644
--- a/Documentation/admin-guide/sysctl/abi.rst
+++ b/Documentation/admin-guide/sysctl/abi.rst
@@ -11,7 +11,7 @@ Documentation for /proc/sys/abi/
 
 Copyright (c) 2020, Stephen Kitt
 
-For general info, see :doc:`index`.
+For general info, see Documentation/admin-guide/sysctl/index.rst.
 
 ------------------------------------------------------------------------------
 
diff --git a/Documentation/admin-guide/sysctl/kernel.rst b/Documentation/admin-guide/sysctl/kernel.rst
index c24f57f2c782..10df7fc6495f 100644
--- a/Documentation/admin-guide/sysctl/kernel.rst
+++ b/Documentation/admin-guide/sysctl/kernel.rst
@@ -9,7 +9,8 @@ Copyright (c) 1998, 1999,  Rik van Riel <riel@nl.linux.org>
 
 Copyright (c) 2009,        Shen Feng<shen@cn.fujitsu.com>
 
-For general info and legal blurb, please look in :doc:`index`.
+For general info and legal blurb, please look in
+Documentation/admin-guide/sysctl/index.rst.
 
 ------------------------------------------------------------------------------
 
@@ -54,7 +55,7 @@ free space valid for 30 seconds.
 acpi_video_flags
 ================
 
-See :doc:`/power/video`. This allows the video resume mode to be set,
+See Documentation/power/video.rst. This allows the video resume mode to be set,
 in a similar fashion to the ``acpi_sleep`` kernel parameter, by
 combining the following values:
 
@@ -89,7 +90,7 @@ is 0x15 and the full version number is 0x234, this file will contain
 the value 340 = 0x154.
 
 See the ``type_of_loader`` and ``ext_loader_type`` fields in
-:doc:`/x86/boot` for additional information.
+Documentation/x86/boot.rst for additional information.
 
 
 bootloader_version (x86 only)
@@ -99,7 +100,7 @@ The complete bootloader version number.  In the example above, this
 file will contain the value 564 = 0x234.
 
 See the ``type_of_loader`` and ``ext_loader_ver`` fields in
-:doc:`/x86/boot` for additional information.
+Documentation/x86/boot.rst for additional information.
 
 
 bpf_stats_enabled
@@ -269,7 +270,7 @@ see the ``hostname(1)`` man page.
 firmware_config
 ===============
 
-See :doc:`/driver-api/firmware/fallback-mechanisms`.
+See Documentation/driver-api/firmware/fallback-mechanisms.rst.
 
 The entries in this directory allow the firmware loader helper
 fallback to be controlled:
@@ -297,7 +298,7 @@ crashes and outputting them to a serial console.
 ftrace_enabled, stack_tracer_enabled
 ====================================
 
-See :doc:`/trace/ftrace`.
+See Documentation/trace/ftrace.rst.
 
 
 hardlockup_all_cpu_backtrace
@@ -325,7 +326,7 @@ when a hard lockup is detected.
 1 Panic on hard lockup.
 = ===========================
 
-See :doc:`/admin-guide/lockup-watchdogs` for more information.
+See Documentation/admin-guide/lockup-watchdogs.rst for more information.
 This can also be set using the nmi_watchdog kernel parameter.
 
 
@@ -586,7 +587,8 @@ in a KVM virtual machine. This default can be overridden by adding::
 
    nmi_watchdog=1
 
-to the guest kernel command line (see :doc:`/admin-guide/kernel-parameters`).
+to the guest kernel command line (see
+Documentation/admin-guide/kernel-parameters.rst).
 
 
 numa_balancing
@@ -1071,7 +1073,7 @@ that support this feature.
 real-root-dev
 =============
 
-See :doc:`/admin-guide/initrd`.
+See Documentation/admin-guide/initrd.rst.
 
 
 reboot-cmd (SPARC only)
@@ -1158,7 +1160,7 @@ will take effect.
 seccomp
 =======
 
-See :doc:`/userspace-api/seccomp_filter`.
+See Documentation/userspace-api/seccomp_filter.rst.
 
 
 sg-big-buff
@@ -1329,7 +1331,7 @@ the boot PROM.
 sysrq
 =====
 
-See :doc:`/admin-guide/sysrq`.
+See Documentation/admin-guide/sysrq.rst.
 
 
 tainted
@@ -1359,15 +1361,16 @@ ORed together. The letters are seen in "Tainted" line of Oops reports.
 131072  `(T)`  The kernel was built with the struct randomization plugin
 ======  =====  ==============================================================
 
-See :doc:`/admin-guide/tainted-kernels` for more information.
+See Documentation/admin-guide/tainted-kernels.rst for more information.
 
 Note:
   writes to this sysctl interface will fail with ``EINVAL`` if the kernel is
   booted with the command line option ``panic_on_taint=<bitmask>,nousertaint``
   and any of the ORed together values being written to ``tainted`` match with
   the bitmask declared on panic_on_taint.
-  See :doc:`/admin-guide/kernel-parameters` for more details on that particular
-  kernel command line option and its optional ``nousertaint`` switch.
+  See Documentation/admin-guide/kernel-parameters.rst for more details on
+  that particular kernel command line option and its optional
+  ``nousertaint`` switch.
 
 threads-max
 ===========
@@ -1391,7 +1394,7 @@ If a value outside of this range is written to ``threads-max`` an
 traceoff_on_warning
 ===================
 
-When set, disables tracing (see :doc:`/trace/ftrace`) when a
+When set, disables tracing (see Documentation/trace/ftrace.rst) when a
 ``WARN()`` is hit.
 
 
@@ -1411,8 +1414,8 @@ will send them to printk() again.
 
 This only works if the kernel was booted with ``tp_printk`` enabled.
 
-See :doc:`/admin-guide/kernel-parameters` and
-:doc:`/trace/boottime-trace`.
+See Documentation/admin-guide/kernel-parameters.rst and
+Documentation/trace/boottime-trace.rst.
 
 
 .. _unaligned-dump-stack:
-- 
2.31.1


^ permalink raw reply related	[flat|nested] 63+ messages in thread

* [PATCH 10/34] docs: block: biodoc.rst: avoid using ReSt :doc:`foo` markup
  2021-06-05 13:17 [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag Mauro Carvalho Chehab
                   ` (8 preceding siblings ...)
  2021-06-05 13:18 ` [PATCH 09/34] docs: admin-guide: sysctl: " Mauro Carvalho Chehab
@ 2021-06-05 13:18 ` Mauro Carvalho Chehab
  2021-06-05 13:18 ` [PATCH 11/34] docs: bpf: bpf_lsm.rst: " Mauro Carvalho Chehab
                   ` (25 subsequent siblings)
  35 siblings, 0 replies; 63+ 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, Jens Axboe, 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/block/biodoc.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/block/biodoc.rst b/Documentation/block/biodoc.rst
index 1d4d71e391af..2098477851a4 100644
--- a/Documentation/block/biodoc.rst
+++ b/Documentation/block/biodoc.rst
@@ -196,7 +196,7 @@ a virtual address mapping (unlike the earlier scheme of virtual address
 do not have a corresponding kernel virtual address space mapping) and
 low-memory pages.
 
-Note: Please refer to :doc:`/core-api/dma-api-howto` for a discussion
+Note: Please refer to Documentation/core-api/dma-api-howto.rst for a discussion
 on PCI high mem DMA aspects and mapping of scatter gather lists, and support
 for 64 bit PCI.
 
-- 
2.31.1


^ permalink raw reply related	[flat|nested] 63+ messages in thread

* [PATCH 11/34] docs: bpf: bpf_lsm.rst: avoid using ReSt :doc:`foo` markup
  2021-06-05 13:17 [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag Mauro Carvalho Chehab
                   ` (9 preceding siblings ...)
  2021-06-05 13:18 ` [PATCH 10/34] docs: block: biodoc.rst: avoid using ReSt " Mauro Carvalho Chehab
@ 2021-06-05 13:18 ` Mauro Carvalho Chehab
  2021-06-05 13:18 ` [PATCH 12/34] docs: core-api: " Mauro Carvalho Chehab
                   ` (24 subsequent siblings)
  35 siblings, 0 replies; 63+ 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, Alexei Starovoitov, Andrii Nakryiko,
	Brendan Jackman, Daniel Borkmann, Florent Revest, John Fastabend,
	KP Singh, Martin KaFai Lau, Song Liu, Yonghong Song, bpf,
	linux-kernel, netdev

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/bpf/bpf_lsm.rst | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/Documentation/bpf/bpf_lsm.rst b/Documentation/bpf/bpf_lsm.rst
index 1c0a75a51d79..0dc3fb0d9544 100644
--- a/Documentation/bpf/bpf_lsm.rst
+++ b/Documentation/bpf/bpf_lsm.rst
@@ -20,10 +20,10 @@ LSM hook:
 Other LSM hooks which can be instrumented can be found in
 ``include/linux/lsm_hooks.h``.
 
-eBPF programs that use :doc:`/bpf/btf` do not need to include kernel headers
-for accessing information from the attached eBPF program's context. They can
-simply declare the structures in the eBPF program and only specify the fields
-that need to be accessed.
+eBPF programs that use Documentation/bpf/btf.rst do not need to include kernel
+headers for accessing information from the attached eBPF program's context.
+They can simply declare the structures in the eBPF program and only specify
+the fields that need to be accessed.
 
 .. code-block:: c
 
@@ -88,8 +88,9 @@ example:
 
 The ``__attribute__((preserve_access_index))`` is a clang feature that allows
 the BPF verifier to update the offsets for the access at runtime using the
-:doc:`/bpf/btf` information. Since the BPF verifier is aware of the types, it
-also validates all the accesses made to the various types in the eBPF program.
+Documentation/bpf/btf.rst information. Since the BPF verifier is aware of the
+types, it also validates all the accesses made to the various types in the
+eBPF program.
 
 Loading
 -------
-- 
2.31.1


^ permalink raw reply related	[flat|nested] 63+ messages in thread

* [PATCH 12/34] docs: core-api: avoid using ReSt :doc:`foo` markup
  2021-06-05 13:17 [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag Mauro Carvalho Chehab
                   ` (10 preceding siblings ...)
  2021-06-05 13:18 ` [PATCH 11/34] docs: bpf: bpf_lsm.rst: " Mauro Carvalho Chehab
@ 2021-06-05 13:18 ` Mauro Carvalho Chehab
  2021-06-05 13:18 ` [PATCH 13/34] docs: dev-tools: testing-overview.rst: " Mauro Carvalho Chehab
                   ` (23 subsequent siblings)
  35 siblings, 0 replies; 63+ 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, Daniel Borkmann, Lukas Bulwahn,
	Robin Murphy, Tomasz Figa, 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/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 ++--
 4 files changed, 7 insertions(+), 6 deletions(-)

diff --git a/Documentation/core-api/bus-virt-phys-mapping.rst b/Documentation/core-api/bus-virt-phys-mapping.rst
index c7bc99cd2e21..c72b24a7d52c 100644
--- a/Documentation/core-api/bus-virt-phys-mapping.rst
+++ b/Documentation/core-api/bus-virt-phys-mapping.rst
@@ -8,7 +8,7 @@ How to access I/O mapped memory from within device drivers
 
 	The virt_to_bus() and bus_to_virt() functions have been
 	superseded by the functionality provided by the PCI DMA interface
-	(see :doc:`/core-api/dma-api-howto`).  They continue
+	(see Documentation/core-api/dma-api-howto.rst).  They continue
 	to be documented below for historical purposes, but new code
 	must not use them. --davidm 00/12/12
 
diff --git a/Documentation/core-api/dma-api.rst b/Documentation/core-api/dma-api.rst
index 00a1d4fa3f9e..6d6d0edd2d27 100644
--- a/Documentation/core-api/dma-api.rst
+++ b/Documentation/core-api/dma-api.rst
@@ -5,7 +5,7 @@ Dynamic DMA mapping using the generic device
 :Author: James E.J. Bottomley <James.Bottomley@HansenPartnership.com>
 
 This document describes the DMA API.  For a more gentle introduction
-of the API (and actual examples), see :doc:`/core-api/dma-api-howto`.
+of the API (and actual examples), see Documentation/core-api/dma-api-howto.rst.
 
 This API is split into two pieces.  Part I describes the basic API.
 Part II describes extensions for supporting non-consistent memory
@@ -479,7 +479,8 @@ without the _attrs suffixes, except that they pass an optional
 dma_attrs.
 
 The interpretation of DMA attributes is architecture-specific, and
-each attribute should be documented in :doc:`/core-api/dma-attributes`.
+each attribute should be documented in
+Documentation/core-api/dma-attributes.rst.
 
 If dma_attrs are 0, the semantics of each of these functions
 is identical to those of the corresponding function
diff --git a/Documentation/core-api/dma-isa-lpc.rst b/Documentation/core-api/dma-isa-lpc.rst
index e59a3d35a93d..17b193603f0a 100644
--- a/Documentation/core-api/dma-isa-lpc.rst
+++ b/Documentation/core-api/dma-isa-lpc.rst
@@ -17,7 +17,7 @@ To do ISA style DMA you need to include two headers::
 	#include <asm/dma.h>
 
 The first is the generic DMA API used to convert virtual addresses to
-bus addresses (see :doc:`/core-api/dma-api` for details).
+bus addresses (see Documentation/core-api/dma-api.rst for details).
 
 The second contains the routines specific to ISA DMA transfers. Since
 this is not present on all platforms make sure you construct your
diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index f1c9d20bd42d..5de2c7a4b1b3 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -48,7 +48,7 @@ Concurrency primitives
 ======================
 
 How Linux keeps everything from happening at the same time.  See
-:doc:`/locking/index` for more related documentation.
+Documentation/locking/index.rst for more related documentation.
 
 .. toctree::
    :maxdepth: 1
@@ -77,7 +77,7 @@ Memory management
 =================
 
 How to allocate and use memory in the kernel.  Note that there is a lot
-more memory-management documentation in :doc:`/vm/index`.
+more memory-management documentation in Documentation/vm/index.rst.
 
 .. toctree::
    :maxdepth: 1
-- 
2.31.1


^ permalink raw reply related	[flat|nested] 63+ messages in thread

* [PATCH 13/34] docs: dev-tools: testing-overview.rst: avoid using ReSt :doc:`foo` markup
  2021-06-05 13:17 [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag Mauro Carvalho Chehab
                   ` (11 preceding siblings ...)
  2021-06-05 13:18 ` [PATCH 12/34] docs: core-api: " Mauro Carvalho Chehab
@ 2021-06-05 13:18 ` Mauro Carvalho Chehab
  2021-06-05 15:43   ` David Gow
  2021-06-05 13:18 ` [PATCH 14/34] docs: dev-tools: kunit: avoid using ReST " Mauro Carvalho Chehab
                   ` (22 subsequent siblings)
  35 siblings, 1 reply; 63+ 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, Daniel Latypov, David Gow, Marco Elver,
	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/dev-tools/testing-overview.rst | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/Documentation/dev-tools/testing-overview.rst b/Documentation/dev-tools/testing-overview.rst
index b5b46709969c..65feb81edb14 100644
--- a/Documentation/dev-tools/testing-overview.rst
+++ b/Documentation/dev-tools/testing-overview.rst
@@ -71,15 +71,15 @@ can be used to verify that a test is executing particular functions or lines
 of code. This is useful for determining how much of the kernel is being tested,
 and for finding corner-cases which are not covered by the appropriate test.
 
-:doc:`gcov` is GCC's coverage testing tool, which can be used with the kernel
-to get global or per-module coverage. Unlike KCOV, it does not record per-task
-coverage. Coverage data can be read from debugfs, and interpreted using the
-usual gcov tooling.
+Documentation/dev-tools/gcov.rst is GCC's coverage testing tool, which can be
+used with the kernel to get global or per-module coverage. Unlike KCOV, it
+does not record per-task coverage. Coverage data can be read from debugfs,
+and interpreted using the usual gcov tooling.
 
-:doc:`kcov` is a feature which can be built in to the kernel to allow
-capturing coverage on a per-task level. It's therefore useful for fuzzing and
-other situations where information about code executed during, for example, a
-single syscall is useful.
+Documentation/dev-tools/kcov.rst is a feature which can be built in to the
+kernel to allow capturing coverage on a per-task level. It's therefore useful
+for fuzzing and other situations where information about code executed during,
+for example, a single syscall is useful.
 
 
 Dynamic Analysis Tools
-- 
2.31.1


^ permalink raw reply related	[flat|nested] 63+ 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
                   ` (12 preceding siblings ...)
  2021-06-05 13:18 ` [PATCH 13/34] docs: dev-tools: testing-overview.rst: " 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:18 ` [PATCH 15/34] docs: devicetree: bindings: submitting-patches.rst: avoid using ReSt " Mauro Carvalho Chehab
                   ` (21 subsequent siblings)
  35 siblings, 2 replies; 63+ 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] 63+ messages in thread

* [PATCH 15/34] docs: devicetree: bindings: submitting-patches.rst: avoid using ReSt :doc:`foo` markup
  2021-06-05 13:17 [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag Mauro Carvalho Chehab
                   ` (13 preceding siblings ...)
  2021-06-05 13:18 ` [PATCH 14/34] docs: dev-tools: kunit: avoid using ReST " Mauro Carvalho Chehab
@ 2021-06-05 13:18 ` Mauro Carvalho Chehab
  2021-06-05 13:18 ` [PATCH 16/34] docs: doc-guide: " Mauro Carvalho Chehab
                   ` (20 subsequent siblings)
  35 siblings, 0 replies; 63+ 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, Nícolas F. R. A. Prado,
	Geert Uytterhoeven, Randy Dunlap, Rob Herring, devicetree,
	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>
---
 .../devicetree/bindings/submitting-patches.rst        | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/Documentation/devicetree/bindings/submitting-patches.rst b/Documentation/devicetree/bindings/submitting-patches.rst
index 104fa8fb2c17..8087780f1685 100644
--- a/Documentation/devicetree/bindings/submitting-patches.rst
+++ b/Documentation/devicetree/bindings/submitting-patches.rst
@@ -7,8 +7,8 @@ Submitting Devicetree (DT) binding patches
 I. For patch submitters
 =======================
 
-  0) Normal patch submission rules from Documentation/process/submitting-patches.rst
-     applies.
+  0) Normal patch submission rules from
+     Documentation/process/submitting-patches.rst applies.
 
   1) The Documentation/ and include/dt-bindings/ portion of the patch should
      be a separate patch. The preferred subject prefix for binding patches is::
@@ -25,8 +25,8 @@ I. For patch submitters
 
        make dt_binding_check
 
-     See Documentation/devicetree/bindings/writing-schema.rst for more details about
-     schema and tools setup.
+     See Documentation/devicetree/bindings/writing-schema.rst for more details
+     about schema and tools setup.
 
   3) DT binding files should be dual licensed. The preferred license tag is
      (GPL-2.0-only OR BSD-2-Clause).
@@ -84,7 +84,8 @@ II. For kernel maintainers
 III. Notes
 ==========
 
-  0) Please see :doc:`ABI` for details regarding devicetree ABI.
+  0) Please see Documentation/devicetree/bindings/ABI.rst for details
+     regarding devicetree ABI.
 
   1) This document is intended as a general familiarization with the process as
      decided at the 2013 Kernel Summit.  When in doubt, the current word of the
-- 
2.31.1


^ permalink raw reply related	[flat|nested] 63+ messages in thread

* [PATCH 16/34] docs: doc-guide: avoid using ReSt :doc:`foo` markup
  2021-06-05 13:17 [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag Mauro Carvalho Chehab
                   ` (14 preceding siblings ...)
  2021-06-05 13:18 ` [PATCH 15/34] docs: devicetree: bindings: submitting-patches.rst: avoid using ReSt " Mauro Carvalho Chehab
@ 2021-06-05 13:18 ` Mauro Carvalho Chehab
  2021-06-05 13:18 ` [PATCH 17/34] docs: driver-api: " Mauro Carvalho Chehab
                   ` (19 subsequent siblings)
  35 siblings, 0 replies; 63+ 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, 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/doc-guide/contributing.rst | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/doc-guide/contributing.rst b/Documentation/doc-guide/contributing.rst
index 67ee3691f91f..207fd93d7c80 100644
--- a/Documentation/doc-guide/contributing.rst
+++ b/Documentation/doc-guide/contributing.rst
@@ -237,10 +237,10 @@ We have been trying to improve the situation through the creation of
 a set of "books" that group documentation for specific readers.  These
 include:
 
- - :doc:`../admin-guide/index`
- - :doc:`../core-api/index`
- - :doc:`../driver-api/index`
- - :doc:`../userspace-api/index`
+ - Documentation/admin-guide/index.rst
+ - Documentation/core-api/index.rst
+ - Documentation/driver-api/index.rst
+ - Documentation/userspace-api/index.rst
 
 As well as this book on documentation itself.
 
-- 
2.31.1


^ permalink raw reply related	[flat|nested] 63+ messages in thread

* [PATCH 17/34] docs: driver-api: avoid using ReSt :doc:`foo` markup
  2021-06-05 13:17 [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag Mauro Carvalho Chehab
                   ` (15 preceding siblings ...)
  2021-06-05 13:18 ` [PATCH 16/34] docs: doc-guide: " Mauro Carvalho Chehab
@ 2021-06-05 13:18 ` Mauro Carvalho Chehab
  2021-06-05 13:18 ` [PATCH 18/34] docs: driver-api: gpio: using-gpio.rst: " Mauro Carvalho Chehab
                   ` (18 subsequent siblings)
  35 siblings, 0 replies; 63+ 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, 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/driver-api/ioctl.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/driver-api/ioctl.rst b/Documentation/driver-api/ioctl.rst
index c455db0e1627..8593cc172f0c 100644
--- a/Documentation/driver-api/ioctl.rst
+++ b/Documentation/driver-api/ioctl.rst
@@ -34,7 +34,7 @@ _IO/_IOR/_IOW/_IOWR
 
 type
    An 8-bit number, often a character literal, specific to a subsystem
-   or driver, and listed in :doc:`../userspace-api/ioctl/ioctl-number`
+   or driver, and listed in Documentation/userspace-api/ioctl/ioctl-number.rst
 
 nr
   An 8-bit number identifying the specific command, unique for a give
-- 
2.31.1


^ permalink raw reply related	[flat|nested] 63+ messages in thread

* [PATCH 18/34] docs: driver-api: gpio: using-gpio.rst: avoid using ReSt :doc:`foo` markup
  2021-06-05 13:17 [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag Mauro Carvalho Chehab
                   ` (16 preceding siblings ...)
  2021-06-05 13:18 ` [PATCH 17/34] docs: driver-api: " Mauro Carvalho Chehab
@ 2021-06-05 13:18 ` Mauro Carvalho Chehab
  2021-06-05 16:25   ` Linus Walleij
  2021-06-05 13:18 ` [PATCH 19/34] docs: driver-api: surface_aggregator: " Mauro Carvalho Chehab
                   ` (17 subsequent siblings)
  35 siblings, 1 reply; 63+ 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, Bartosz Golaszewski, Linus Walleij,
	linux-gpio, 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/driver-api/gpio/using-gpio.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/driver-api/gpio/using-gpio.rst b/Documentation/driver-api/gpio/using-gpio.rst
index dda069444032..64c8d3f76c3a 100644
--- a/Documentation/driver-api/gpio/using-gpio.rst
+++ b/Documentation/driver-api/gpio/using-gpio.rst
@@ -9,13 +9,13 @@ with them.
 
 For examples of already existing generic drivers that will also be good
 examples for any other kernel drivers you want to author, refer to
-:doc:`drivers-on-gpio`
+Documentation/driver-api/gpio/drivers-on-gpio.rst
 
 For any kind of mass produced system you want to support, such as servers,
 laptops, phones, tablets, routers, and any consumer or office or business goods
 using appropriate kernel drivers is paramount. Submit your code for inclusion
 in the upstream Linux kernel when you feel it is mature enough and you will get
-help to refine it, see :doc:`../../process/submitting-patches`.
+help to refine it, see Documentation/process/submitting-patches.rst.
 
 In Linux GPIO lines also have a userspace ABI.
 
-- 
2.31.1


^ permalink raw reply related	[flat|nested] 63+ messages in thread

* [PATCH 19/34] docs: driver-api: surface_aggregator: avoid using ReSt :doc:`foo` markup
  2021-06-05 13:17 [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag Mauro Carvalho Chehab
                   ` (17 preceding siblings ...)
  2021-06-05 13:18 ` [PATCH 18/34] docs: driver-api: gpio: using-gpio.rst: " Mauro Carvalho Chehab
@ 2021-06-05 13:18 ` Mauro Carvalho Chehab
  2021-06-05 14:14   ` Maximilian Luz
  2021-06-05 13:18 ` [PATCH 20/34] docs: driver-api: usb: " Mauro Carvalho Chehab
                   ` (16 subsequent siblings)
  35 siblings, 1 reply; 63+ 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, Hans de Goede, Maximilian Luz, 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>
---
 .../surface_aggregator/clients/index.rst          |  3 ++-
 .../driver-api/surface_aggregator/internal.rst    | 15 ++++++++-------
 .../driver-api/surface_aggregator/overview.rst    |  6 ++++--
 3 files changed, 14 insertions(+), 10 deletions(-)

diff --git a/Documentation/driver-api/surface_aggregator/clients/index.rst b/Documentation/driver-api/surface_aggregator/clients/index.rst
index 98ea9946b8a2..30160513afa5 100644
--- a/Documentation/driver-api/surface_aggregator/clients/index.rst
+++ b/Documentation/driver-api/surface_aggregator/clients/index.rst
@@ -5,7 +5,8 @@ Client Driver Documentation
 ===========================
 
 This is the documentation for client drivers themselves. Refer to
-:doc:`../client` for documentation on how to write client drivers.
+Documentation/driver-api/surface_aggregator/client.rst for documentation
+on how to write client drivers.
 
 .. toctree::
    :maxdepth: 1
diff --git a/Documentation/driver-api/surface_aggregator/internal.rst b/Documentation/driver-api/surface_aggregator/internal.rst
index 72704734982a..8c7c80c9f418 100644
--- a/Documentation/driver-api/surface_aggregator/internal.rst
+++ b/Documentation/driver-api/surface_aggregator/internal.rst
@@ -87,10 +87,11 @@ native SSAM devices, i.e. devices that are not defined in ACPI and not
 implemented as platform devices, via |ssam_device| and |ssam_device_driver|
 simplify management of client devices and client drivers.
 
-Refer to :doc:`client` for documentation regarding the client device/driver
-API and interface options for other kernel drivers. It is recommended to
-familiarize oneself with that chapter and the :doc:`ssh` before continuing
-with the architectural overview below.
+Refer to Documentation/driver-api/surface_aggregator/client.rst for
+documentation regarding the client device/driver API and interface options
+for other kernel drivers. It is recommended to familiarize oneself with
+that chapter and the Documentation/driver-api/surface_aggregator/ssh.rst
+before continuing with the architectural overview below.
 
 
 Packet Transport Layer
@@ -190,9 +191,9 @@ with success on the transmitter thread.
 
 Transmission of sequenced packets is limited by the number of concurrently
 pending packets, i.e. a limit on how many packets may be waiting for an ACK
-from the EC in parallel. This limit is currently set to one (see :doc:`ssh`
-for the reasoning behind this). Control packets (i.e. ACK and NAK) can
-always be transmitted.
+from the EC in parallel. This limit is currently set to one (see
+Documentation/driver-api/surface_aggregator/ssh.rst for the reasoning behind
+this). Control packets (i.e. ACK and NAK) can always be transmitted.
 
 Receiver Thread
 ---------------
diff --git a/Documentation/driver-api/surface_aggregator/overview.rst b/Documentation/driver-api/surface_aggregator/overview.rst
index 1e9d57e50063..26415e1ab7da 100644
--- a/Documentation/driver-api/surface_aggregator/overview.rst
+++ b/Documentation/driver-api/surface_aggregator/overview.rst
@@ -73,5 +73,7 @@ being a direct response to a previous request. We may also refer to requests
 without response as commands. In general, events need to be enabled via one
 of multiple dedicated requests before they are sent by the EC.
 
-See :doc:`ssh` for a more technical protocol documentation and
-:doc:`internal` for an overview of the internal driver architecture.
+See Documentation/driver-api/surface_aggregator/ssh.rst for a
+more technical protocol documentation and
+Documentation/driver-api/surface_aggregator/internal.rst for an
+overview of the internal driver architecture.
-- 
2.31.1


^ permalink raw reply related	[flat|nested] 63+ messages in thread

* [PATCH 20/34] docs: driver-api: usb: avoid using ReSt :doc:`foo` markup
  2021-06-05 13:17 [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag Mauro Carvalho Chehab
                   ` (18 preceding siblings ...)
  2021-06-05 13:18 ` [PATCH 19/34] docs: driver-api: surface_aggregator: " Mauro Carvalho Chehab
@ 2021-06-05 13:18 ` Mauro Carvalho Chehab
  2021-06-05 13:18 ` [PATCH 21/34] docs: firmware-guide: acpi: " Mauro Carvalho Chehab
                   ` (15 subsequent siblings)
  35 siblings, 0 replies; 63+ 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, 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/driver-api/usb/dma.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/driver-api/usb/dma.rst b/Documentation/driver-api/usb/dma.rst
index 2b3dbd3265b4..d32c27e11b90 100644
--- a/Documentation/driver-api/usb/dma.rst
+++ b/Documentation/driver-api/usb/dma.rst
@@ -10,7 +10,7 @@ API overview
 
 The big picture is that USB drivers can continue to ignore most DMA issues,
 though they still must provide DMA-ready buffers (see
-:doc:`/core-api/dma-api-howto`).  That's how they've worked through
+Documentation/core-api/dma-api-howto.rst).  That's how they've worked through
 the 2.4 (and earlier) kernels, or they can now be DMA-aware.
 
 DMA-aware usb drivers:
@@ -60,7 +60,7 @@ and effects like cache-trashing can impose subtle penalties.
   force a consistent memory access ordering by using memory barriers.  It's
   not using a streaming DMA mapping, so it's good for small transfers on
   systems where the I/O would otherwise thrash an IOMMU mapping.  (See
-  :doc:`/core-api/dma-api-howto` for definitions of "coherent" and
+  Documentation/core-api/dma-api-howto.rst for definitions of "coherent" and
   "streaming" DMA mappings.)
 
   Asking for 1/Nth of a page (as well as asking for N pages) is reasonably
@@ -91,7 +91,7 @@ Working with existing buffers
 Existing buffers aren't usable for DMA without first being mapped into the
 DMA address space of the device.  However, most buffers passed to your
 driver can safely be used with such DMA mapping.  (See the first section
-of :doc:`/core-api/dma-api-howto`, titled "What memory is DMA-able?")
+of Documentation/core-api/dma-api-howto.rst, titled "What memory is DMA-able?")
 
 - When you're using scatterlists, you can map everything at once.  On some
   systems, this kicks in an IOMMU and turns the scatterlists into single
-- 
2.31.1


^ permalink raw reply related	[flat|nested] 63+ messages in thread

* [PATCH 21/34] docs: firmware-guide: acpi: avoid using ReSt :doc:`foo` markup
  2021-06-05 13:17 [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag Mauro Carvalho Chehab
                   ` (19 preceding siblings ...)
  2021-06-05 13:18 ` [PATCH 20/34] docs: driver-api: usb: " Mauro Carvalho Chehab
@ 2021-06-05 13:18 ` Mauro Carvalho Chehab
  2021-06-05 13:18 ` [PATCH 22/34] docs: hwmon: adm1177.rst: " Mauro Carvalho Chehab
                   ` (14 subsequent siblings)
  35 siblings, 0 replies; 63+ 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, Alexander A. Klimov, Rafael J. Wysocki,
	Len Brown, Sakari Ailus, Vishal Verma, linux-acpi, 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>
---
 .../firmware-guide/acpi/dsd/data-node-references.rst       | 3 ++-
 Documentation/firmware-guide/acpi/dsd/graph.rst            | 2 +-
 Documentation/firmware-guide/acpi/enumeration.rst          | 7 ++++---
 3 files changed, 7 insertions(+), 5 deletions(-)

diff --git a/Documentation/firmware-guide/acpi/dsd/data-node-references.rst b/Documentation/firmware-guide/acpi/dsd/data-node-references.rst
index 9b17dc77d18c..b7ad47df49de 100644
--- a/Documentation/firmware-guide/acpi/dsd/data-node-references.rst
+++ b/Documentation/firmware-guide/acpi/dsd/data-node-references.rst
@@ -79,7 +79,8 @@ the ANOD object which is also the final target node of the reference.
 	    })
 	}
 
-Please also see a graph example in :doc:`graph`.
+Please also see a graph example in
+Documentation/firmware-guide/acpi/dsd/graph.rst.
 
 References
 ==========
diff --git a/Documentation/firmware-guide/acpi/dsd/graph.rst b/Documentation/firmware-guide/acpi/dsd/graph.rst
index 7072db801aeb..4341299aa937 100644
--- a/Documentation/firmware-guide/acpi/dsd/graph.rst
+++ b/Documentation/firmware-guide/acpi/dsd/graph.rst
@@ -174,4 +174,4 @@ References
     referenced 2016-10-04.
 
 [7] _DSD Device Properties Usage Rules.
-    :doc:`../DSD-properties-rules`
+    Documentation/firmware-guide/acpi/DSD-properties-rules.rst
diff --git a/Documentation/firmware-guide/acpi/enumeration.rst b/Documentation/firmware-guide/acpi/enumeration.rst
index 9f0d5c854fa4..18074eb71860 100644
--- a/Documentation/firmware-guide/acpi/enumeration.rst
+++ b/Documentation/firmware-guide/acpi/enumeration.rst
@@ -339,8 +339,8 @@ a code like this::
 There are also devm_* versions of these functions which release the
 descriptors once the device is released.
 
-See Documentation/firmware-guide/acpi/gpio-properties.rst for more information about the
-_DSD binding related to GPIOs.
+See Documentation/firmware-guide/acpi/gpio-properties.rst for more information
+about the _DSD binding related to GPIOs.
 
 MFD devices
 ===========
@@ -460,7 +460,8 @@ the _DSD of the device object itself or the _DSD of its ancestor in the
 Otherwise, the _DSD itself is regarded as invalid and therefore the "compatible"
 property returned by it is meaningless.
 
-Refer to :doc:`DSD-properties-rules` for more information.
+Refer to Documentation/firmware-guide/acpi/DSD-properties-rules.rst for more
+information.
 
 PCI hierarchy representation
 ============================
-- 
2.31.1


^ permalink raw reply related	[flat|nested] 63+ messages in thread

* [PATCH 22/34] docs: hwmon: adm1177.rst: avoid using ReSt :doc:`foo` markup
  2021-06-05 13:17 [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag Mauro Carvalho Chehab
                   ` (20 preceding siblings ...)
  2021-06-05 13:18 ` [PATCH 21/34] docs: firmware-guide: acpi: " Mauro Carvalho Chehab
@ 2021-06-05 13:18 ` Mauro Carvalho Chehab
  2021-06-06 13:01   ` Guenter Roeck
  2021-06-05 13:18 ` [PATCH 23/34] docs: i2c: " Mauro Carvalho Chehab
                   ` (13 subsequent siblings)
  35 siblings, 1 reply; 63+ 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, Guenter Roeck, Jean Delvare, linux-hwmon,
	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/hwmon/adm1177.rst | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/hwmon/adm1177.rst b/Documentation/hwmon/adm1177.rst
index 471be1e98d6f..1c85a2af92bf 100644
--- a/Documentation/hwmon/adm1177.rst
+++ b/Documentation/hwmon/adm1177.rst
@@ -20,7 +20,8 @@ Usage Notes
 -----------
 
 This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see :doc:`/i2c/instantiating-devices` for details.
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst
+for details.
 
 
 Sysfs entries
-- 
2.31.1


^ permalink raw reply related	[flat|nested] 63+ messages in thread

* [PATCH 23/34] docs: i2c: avoid using ReSt :doc:`foo` markup
  2021-06-05 13:17 [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag Mauro Carvalho Chehab
                   ` (21 preceding siblings ...)
  2021-06-05 13:18 ` [PATCH 22/34] docs: hwmon: adm1177.rst: " Mauro Carvalho Chehab
@ 2021-06-05 13:18 ` Mauro Carvalho Chehab
  2021-06-05 15:13   ` Wolfram Sang
  2021-06-05 13:18 ` [PATCH 24/34] docs: kernel-hacking: hacking.rst: " Mauro Carvalho Chehab
                   ` (12 subsequent siblings)
  35 siblings, 1 reply; 63+ 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, Wolfram Sang, linux-i2c, 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/i2c/instantiating-devices.rst | 2 +-
 Documentation/i2c/old-module-parameters.rst | 3 ++-
 Documentation/i2c/smbus-protocol.rst        | 4 ++--
 3 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/Documentation/i2c/instantiating-devices.rst b/Documentation/i2c/instantiating-devices.rst
index e558e0a77e0c..890c9360ce19 100644
--- a/Documentation/i2c/instantiating-devices.rst
+++ b/Documentation/i2c/instantiating-devices.rst
@@ -59,7 +59,7 @@ Declare the I2C devices via ACPI
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 ACPI can also describe I2C devices. There is special documentation for this
-which is currently located at :doc:`../firmware-guide/acpi/enumeration`.
+which is currently located at Documentation/firmware-guide/acpi/enumeration.rst.
 
 
 Declare the I2C devices in board files
diff --git a/Documentation/i2c/old-module-parameters.rst b/Documentation/i2c/old-module-parameters.rst
index 38e55829dee8..b08b6daabce9 100644
--- a/Documentation/i2c/old-module-parameters.rst
+++ b/Documentation/i2c/old-module-parameters.rst
@@ -17,7 +17,8 @@ address), ``force`` (to forcibly attach the driver to a given device) and
 With the conversion of the I2C subsystem to the standard device driver
 binding model, it became clear that these per-module parameters were no
 longer needed, and that a centralized implementation was possible. The new,
-sysfs-based interface is described in :doc:`instantiating-devices`, section
+sysfs-based interface is described in
+Documentation/i2c/instantiating-devices.rst, section
 "Method 4: Instantiate from user-space".
 
 Below is a mapping from the old module parameters to the new interface.
diff --git a/Documentation/i2c/smbus-protocol.rst b/Documentation/i2c/smbus-protocol.rst
index 64689d19dd51..9e07e6bbe6a3 100644
--- a/Documentation/i2c/smbus-protocol.rst
+++ b/Documentation/i2c/smbus-protocol.rst
@@ -27,8 +27,8 @@ a different protocol operation entirely.
 Each transaction type corresponds to a functionality flag. Before calling a
 transaction function, a device driver should always check (just once) for
 the corresponding functionality flag to ensure that the underlying I2C
-adapter supports the transaction in question. See :doc:`functionality` for
-the details.
+adapter supports the transaction in question. See
+Documentation/i2c/functionality.rst for the details.
 
 
 Key to symbols
-- 
2.31.1


^ permalink raw reply related	[flat|nested] 63+ messages in thread

* [PATCH 24/34] docs: kernel-hacking: hacking.rst: avoid using ReSt :doc:`foo` markup
  2021-06-05 13:17 [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag Mauro Carvalho Chehab
                   ` (22 preceding siblings ...)
  2021-06-05 13:18 ` [PATCH 23/34] docs: i2c: " Mauro Carvalho Chehab
@ 2021-06-05 13:18 ` Mauro Carvalho Chehab
  2021-06-05 13:18 ` [PATCH 25/34] docs: networking: devlink: " Mauro Carvalho Chehab
                   ` (11 subsequent siblings)
  35 siblings, 0 replies; 63+ 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, Joe Pater, 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/kernel-hacking/hacking.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/kernel-hacking/hacking.rst b/Documentation/kernel-hacking/hacking.rst
index 451523424942..df65c19aa7df 100644
--- a/Documentation/kernel-hacking/hacking.rst
+++ b/Documentation/kernel-hacking/hacking.rst
@@ -601,7 +601,7 @@ Defined in ``include/linux/export.h``
 
 This is the variant of `EXPORT_SYMBOL()` that allows specifying a symbol
 namespace. Symbol Namespaces are documented in
-:doc:`../core-api/symbol-namespaces`
+Documentation/core-api/symbol-namespaces.rst
 
 :c:func:`EXPORT_SYMBOL_NS_GPL()`
 --------------------------------
@@ -610,7 +610,7 @@ Defined in ``include/linux/export.h``
 
 This is the variant of `EXPORT_SYMBOL_GPL()` that allows specifying a symbol
 namespace. Symbol Namespaces are documented in
-:doc:`../core-api/symbol-namespaces`
+Documentation/core-api/symbol-namespaces.rst
 
 Routines and Conventions
 ========================
-- 
2.31.1


^ permalink raw reply related	[flat|nested] 63+ messages in thread

* [PATCH 25/34] docs: networking: devlink: avoid using ReSt :doc:`foo` markup
  2021-06-05 13:17 [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag Mauro Carvalho Chehab
                   ` (23 preceding siblings ...)
  2021-06-05 13:18 ` [PATCH 24/34] docs: kernel-hacking: hacking.rst: " Mauro Carvalho Chehab
@ 2021-06-05 13:18 ` Mauro Carvalho Chehab
  2021-06-05 13:18 ` [PATCH 26/34] docs: PCI: endpoint: pci-endpoint-cfs.rst: " Mauro Carvalho Chehab
                   ` (10 subsequent siblings)
  35 siblings, 0 replies; 63+ 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, David S. Miller, Jakub Kicinski,
	Jiri Pirko, linux-kernel, netdev

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/networking/devlink/devlink-region.rst | 2 +-
 Documentation/networking/devlink/devlink-trap.rst   | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/networking/devlink/devlink-region.rst b/Documentation/networking/devlink/devlink-region.rst
index 3654c3e9658f..58fe95e9a49d 100644
--- a/Documentation/networking/devlink/devlink-region.rst
+++ b/Documentation/networking/devlink/devlink-region.rst
@@ -22,7 +22,7 @@ The major benefit to creating a region is to provide access to internal
 address regions that are otherwise inaccessible to the user.
 
 Regions may also be used to provide an additional way to debug complex error
-states, but see also :doc:`devlink-health`
+states, but see also Documentation/networking/devlink/devlink-health.rst
 
 Regions may optionally support capturing a snapshot on demand via the
 ``DEVLINK_CMD_REGION_NEW`` netlink message. A driver wishing to allow
diff --git a/Documentation/networking/devlink/devlink-trap.rst b/Documentation/networking/devlink/devlink-trap.rst
index 935b6397e8cf..efa5f7f42c88 100644
--- a/Documentation/networking/devlink/devlink-trap.rst
+++ b/Documentation/networking/devlink/devlink-trap.rst
@@ -495,8 +495,8 @@ help debug packet drops caused by these exceptions. The following list includes
 links to the description of driver-specific traps registered by various device
 drivers:
 
-  * :doc:`netdevsim`
-  * :doc:`mlxsw`
+  * Documentation/networking/devlink/netdevsim.rst
+  * Documentation/networking/devlink/mlxsw.rst
 
 .. _Generic-Packet-Trap-Groups:
 
-- 
2.31.1


^ permalink raw reply related	[flat|nested] 63+ messages in thread

* [PATCH 26/34] docs: PCI: endpoint: pci-endpoint-cfs.rst: avoid using ReSt :doc:`foo` markup
  2021-06-05 13:17 [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag Mauro Carvalho Chehab
                   ` (24 preceding siblings ...)
  2021-06-05 13:18 ` [PATCH 25/34] docs: networking: devlink: " Mauro Carvalho Chehab
@ 2021-06-05 13:18 ` Mauro Carvalho Chehab
  2021-06-10 23:46   ` Bjorn Helgaas
  2021-06-05 13:18 ` [PATCH 27/34] docs: PCI: pci.rst: " Mauro Carvalho Chehab
                   ` (9 subsequent siblings)
  35 siblings, 1 reply; 63+ 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, Bjorn Helgaas, Kishon Vijay Abraham I,
	Lorenzo Pieralisi, linux-kernel, linux-pci

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/PCI/endpoint/pci-endpoint-cfs.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/PCI/endpoint/pci-endpoint-cfs.rst b/Documentation/PCI/endpoint/pci-endpoint-cfs.rst
index 696f8eeb4738..db609b97ad58 100644
--- a/Documentation/PCI/endpoint/pci-endpoint-cfs.rst
+++ b/Documentation/PCI/endpoint/pci-endpoint-cfs.rst
@@ -125,4 +125,4 @@ all the EPF devices are created and linked with the EPC device.
 						| interrupt_pin
 						| function
 
-[1] :doc:`pci-endpoint`
+[1] Documentation/PCI/endpoint/pci-endpoint.rst
-- 
2.31.1


^ permalink raw reply related	[flat|nested] 63+ messages in thread

* [PATCH 27/34] docs: PCI: pci.rst: avoid using ReSt :doc:`foo` markup
  2021-06-05 13:17 [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag Mauro Carvalho Chehab
                   ` (25 preceding siblings ...)
  2021-06-05 13:18 ` [PATCH 26/34] docs: PCI: endpoint: pci-endpoint-cfs.rst: " Mauro Carvalho Chehab
@ 2021-06-05 13:18 ` Mauro Carvalho Chehab
  2021-06-10 23:46   ` Bjorn Helgaas
  2021-06-05 13:18 ` [PATCH 28/34] docs: process: submitting-patches.rst: " Mauro Carvalho Chehab
                   ` (8 subsequent siblings)
  35 siblings, 1 reply; 63+ 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, Bjorn Helgaas, linux-kernel, linux-pci

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/PCI/pci.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/PCI/pci.rst b/Documentation/PCI/pci.rst
index 814b40f8360b..fa651e25d98c 100644
--- a/Documentation/PCI/pci.rst
+++ b/Documentation/PCI/pci.rst
@@ -265,7 +265,7 @@ Set the DMA mask size
 ---------------------
 .. note::
    If anything below doesn't make sense, please refer to
-   :doc:`/core-api/dma-api`. This section is just a reminder that
+   Documentation/core-api/dma-api.rst. This section is just a reminder that
    drivers need to indicate DMA capabilities of the device and is not
    an authoritative source for DMA interfaces.
 
@@ -291,7 +291,7 @@ Many 64-bit "PCI" devices (before PCI-X) and some PCI-X devices are
 Setup shared control data
 -------------------------
 Once the DMA masks are set, the driver can allocate "consistent" (a.k.a. shared)
-memory.  See :doc:`/core-api/dma-api` for a full description of
+memory.  See Documentation/core-api/dma-api.rst for a full description of
 the DMA APIs. This section is just a reminder that it needs to be done
 before enabling DMA on the device.
 
@@ -421,7 +421,7 @@ owners if there is one.
 
 Then clean up "consistent" buffers which contain the control data.
 
-See :doc:`/core-api/dma-api` for details on unmapping interfaces.
+See Documentation/core-api/dma-api.rst for details on unmapping interfaces.
 
 
 Unregister from other subsystems
-- 
2.31.1


^ permalink raw reply related	[flat|nested] 63+ messages in thread

* [PATCH 28/34] docs: process: submitting-patches.rst: avoid using ReSt :doc:`foo` markup
  2021-06-05 13:17 [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag Mauro Carvalho Chehab
                   ` (26 preceding siblings ...)
  2021-06-05 13:18 ` [PATCH 27/34] docs: PCI: pci.rst: " Mauro Carvalho Chehab
@ 2021-06-05 13:18 ` Mauro Carvalho Chehab
  2021-06-05 13:18 ` [PATCH 29/34] docs: security: landlock.rst: " Mauro Carvalho Chehab
                   ` (7 subsequent siblings)
  35 siblings, 0 replies; 63+ 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, Borislav Petkov, Drew DeVault,
	Greg Kroah-Hartman, Krzysztof Kozlowski, Lee Jones, 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/process/submitting-patches.rst | 32 +++++++++-----------
 1 file changed, 15 insertions(+), 17 deletions(-)

diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
index c66a19201deb..0852bcf73630 100644
--- a/Documentation/process/submitting-patches.rst
+++ b/Documentation/process/submitting-patches.rst
@@ -10,10 +10,11 @@ can greatly increase the chances of your change being accepted.
 
 This document contains a large number of suggestions in a relatively terse
 format.  For detailed information on how the kernel development process
-works, see :doc:`development-process`. Also, read :doc:`submit-checklist`
+works, see Documentation/process/development-process.rst. Also, read
+Documentation/process/submit-checklist.rst
 for a list of items to check before submitting code.  If you are submitting
-a driver, also read :doc:`submitting-drivers`; for device tree binding patches,
-read :doc:`submitting-patches`.
+a driver, also read Documentation/process/submitting-drivers.rst; for device
+tree binding patches, read Documentation/process/submitting-patches.rst.
 
 This documentation assumes that you're using ``git`` to prepare your patches.
 If you're unfamiliar with ``git``, you would be well-advised to learn how to
@@ -178,8 +179,7 @@ Style-check your changes
 ------------------------
 
 Check your patch for basic style violations, details of which can be
-found in
-:ref:`Documentation/process/coding-style.rst <codingstyle>`.
+found in Documentation/process/coding-style.rst.
 Failure to do so simply wastes
 the reviewers time and will get your patch rejected, probably
 without even being read.
@@ -238,7 +238,7 @@ If you have a patch that fixes an exploitable security bug, send that patch
 to security@kernel.org.  For severe bugs, a short embargo may be considered
 to allow distributors to get the patch out to users; in such cases,
 obviously, the patch should not be sent to any public lists. See also
-:doc:`/admin-guide/security-bugs`.
+Documentation/admin-guide/security-bugs.rst.
 
 Patches that fix a severe bug in a released kernel should be directed
 toward the stable maintainers by putting a line like this::
@@ -246,9 +246,8 @@ toward the stable maintainers by putting a line like this::
   Cc: stable@vger.kernel.org
 
 into the sign-off area of your patch (note, NOT an email recipient).  You
-should also read
-:ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>`
-in addition to this file.
+should also read Documentation/process/stable-kernel-rules.rst
+in addition to this document.
 
 If changes affect userland-kernel interfaces, please send the MAN-PAGES
 maintainer (as listed in the MAINTAINERS file) a man-pages patch, or at
@@ -305,8 +304,8 @@ decreasing the likelihood of your MIME-attached change being accepted.
 Exception:  If your mailer is mangling patches then someone may ask
 you to re-send them using MIME.
 
-See :doc:`/process/email-clients` for hints about configuring your e-mail
-client so that it sends your patches untouched.
+See Documentation/process/email-clients.rst for hints about configuring
+your e-mail client so that it sends your patches untouched.
 
 Respond to review comments
 --------------------------
@@ -324,7 +323,7 @@ for their time.  Code review is a tiring and time-consuming process, and
 reviewers sometimes get grumpy.  Even in that case, though, respond
 politely and address the problems they have pointed out.
 
-See :doc:`email-clients` for recommendations on email
+See Documentation/process/email-clients.rst for recommendations on email
 clients and mailing list etiquette.
 
 
@@ -562,10 +561,10 @@ method for indicating a bug fixed by the patch. See :ref:`describe_changes`
 for more details.
 
 Note: Attaching a Fixes: tag does not subvert the stable kernel rules
-process nor the requirement to Cc: stable@vger.kernel.org on all stable 
+process nor the requirement to Cc: stable@vger.kernel.org on all stable
 patch candidates. For more information, please read
-:ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>`
-     
+Documentation/process/stable-kernel-rules.rst.
+
 .. _the_canonical_patch_format:
 
 The canonical patch format
@@ -824,8 +823,7 @@ Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer".
 NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people!
   <https://lore.kernel.org/r/20050711.125305.08322243.davem@davemloft.net>
 
-Kernel Documentation/process/coding-style.rst:
-  :ref:`Documentation/process/coding-style.rst <codingstyle>`
+Kernel Documentation/process/coding-style.rst
 
 Linus Torvalds's mail on the canonical patch format:
   <https://lore.kernel.org/r/Pine.LNX.4.58.0504071023190.28951@ppc970.osdl.org>
-- 
2.31.1


^ permalink raw reply related	[flat|nested] 63+ messages in thread

* [PATCH 29/34] docs: security: landlock.rst: avoid using ReSt :doc:`foo` markup
  2021-06-05 13:17 [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag Mauro Carvalho Chehab
                   ` (27 preceding siblings ...)
  2021-06-05 13:18 ` [PATCH 28/34] docs: process: submitting-patches.rst: " Mauro Carvalho Chehab
@ 2021-06-05 13:18 ` Mauro Carvalho Chehab
  2021-06-05 13:18 ` [PATCH 30/34] docs: trace: coresight: coresight.rst: " Mauro Carvalho Chehab
                   ` (6 subsequent siblings)
  35 siblings, 0 replies; 63+ 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, Mickaël Salaün, linux-kernel,
	linux-security-module

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/security/landlock.rst | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/security/landlock.rst b/Documentation/security/landlock.rst
index 2e84925ae971..3df68cb1d10f 100644
--- a/Documentation/security/landlock.rst
+++ b/Documentation/security/landlock.rst
@@ -25,7 +25,8 @@ Any user can enforce Landlock rulesets on their processes.  They are merged and
 evaluated according to the inherited ones in a way that ensures that only more
 constraints can be added.
 
-User space documentation can be found here: :doc:`/userspace-api/landlock`.
+User space documentation can be found here:
+Documentation/userspace-api/landlock.rst.
 
 Guiding principles for safe access controls
 ===========================================
-- 
2.31.1


^ permalink raw reply related	[flat|nested] 63+ messages in thread

* [PATCH 30/34] docs: trace: coresight: coresight.rst: avoid using ReSt :doc:`foo` markup
  2021-06-05 13:17 [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag Mauro Carvalho Chehab
                   ` (28 preceding siblings ...)
  2021-06-05 13:18 ` [PATCH 29/34] docs: security: landlock.rst: " Mauro Carvalho Chehab
@ 2021-06-05 13:18 ` Mauro Carvalho Chehab
  2021-06-08 15:23   ` Mathieu Poirier
  2021-06-05 13:18 ` [PATCH 31/34] docs: trace: ftrace.rst: " Mauro Carvalho Chehab
                   ` (5 subsequent siblings)
  35 siblings, 1 reply; 63+ 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, 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


^ permalink raw reply related	[flat|nested] 63+ messages in thread

* [PATCH 31/34] docs: trace: ftrace.rst: avoid using ReSt :doc:`foo` markup
  2021-06-05 13:17 [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag Mauro Carvalho Chehab
                   ` (29 preceding siblings ...)
  2021-06-05 13:18 ` [PATCH 30/34] docs: trace: coresight: coresight.rst: " Mauro Carvalho Chehab
@ 2021-06-05 13:18 ` Mauro Carvalho Chehab
  2021-06-05 13:18 ` [PATCH 32/34] docs: userspace-api: landlock.rst: " Mauro Carvalho Chehab
                   ` (4 subsequent siblings)
  35 siblings, 0 replies; 63+ 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, Ingo Molnar, Steven Rostedt, 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/ftrace.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/trace/ftrace.rst b/Documentation/trace/ftrace.rst
index b88c6b79db3e..cfc81e98e0b8 100644
--- a/Documentation/trace/ftrace.rst
+++ b/Documentation/trace/ftrace.rst
@@ -40,7 +40,7 @@ See events.rst for more information.
 Implementation Details
 ----------------------
 
-See :doc:`ftrace-design` for details for arch porters and such.
+See Documentation/trace/ftrace-design.rst for details for arch porters and such.
 
 
 The File System
-- 
2.31.1


^ permalink raw reply related	[flat|nested] 63+ messages in thread

* [PATCH 32/34] docs: userspace-api: landlock.rst: avoid using ReSt :doc:`foo` markup
  2021-06-05 13:17 [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag Mauro Carvalho Chehab
                   ` (30 preceding siblings ...)
  2021-06-05 13:18 ` [PATCH 31/34] docs: trace: ftrace.rst: " Mauro Carvalho Chehab
@ 2021-06-05 13:18 ` Mauro Carvalho Chehab
  2021-06-05 13:18 ` [PATCH 33/34] docs: virt: kvm: s390-pv-boot.rst: " Mauro Carvalho Chehab
                   ` (3 subsequent siblings)
  35 siblings, 0 replies; 63+ 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, Mickaël Salaün, linux-kernel,
	linux-security-module

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/userspace-api/landlock.rst | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/Documentation/userspace-api/landlock.rst b/Documentation/userspace-api/landlock.rst
index 62c9361a3c7f..f35552ff19ba 100644
--- a/Documentation/userspace-api/landlock.rst
+++ b/Documentation/userspace-api/landlock.rst
@@ -145,7 +145,8 @@ Bind mounts and OverlayFS
 
 Landlock enables to restrict access to file hierarchies, which means that these
 access rights can be propagated with bind mounts (cf.
-:doc:`/filesystems/sharedsubtree`) but not with :doc:`/filesystems/overlayfs`.
+Documentation/filesystems/sharedsubtree.rst) but not with
+Documentation/filesystems/overlayfs.rst.
 
 A bind mount mirrors a source file hierarchy to a destination.  The destination
 hierarchy is then composed of the exact same files, on which Landlock rules can
@@ -170,8 +171,8 @@ Inheritance
 
 Every new thread resulting from a :manpage:`clone(2)` inherits Landlock domain
 restrictions from its parent.  This is similar to the seccomp inheritance (cf.
-:doc:`/userspace-api/seccomp_filter`) or any other LSM dealing with task's
-:manpage:`credentials(7)`.  For instance, one process's thread may apply
+Documentation/userspace-api/seccomp_filter.rst) or any other LSM dealing with
+task's :manpage:`credentials(7)`.  For instance, one process's thread may apply
 Landlock rules to itself, but they will not be automatically applied to other
 sibling threads (unlike POSIX thread credential changes, cf.
 :manpage:`nptl(7)`).
@@ -278,7 +279,7 @@ Memory usage
 ------------
 
 Kernel memory allocated to create rulesets is accounted and can be restricted
-by the :doc:`/admin-guide/cgroup-v1/memory`.
+by the Documentation/admin-guide/cgroup-v1/memory.rst.
 
 Questions and answers
 =====================
@@ -303,7 +304,7 @@ issues, especially when untrusted processes can manipulate them (cf.
 Additional documentation
 ========================
 
-* :doc:`/security/landlock`
+* Documentation/security/landlock.rst
 * https://landlock.io
 
 .. Links
-- 
2.31.1


^ permalink raw reply related	[flat|nested] 63+ messages in thread

* [PATCH 33/34] docs: virt: kvm: s390-pv-boot.rst: avoid using ReSt :doc:`foo` markup
  2021-06-05 13:17 [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag Mauro Carvalho Chehab
                   ` (31 preceding siblings ...)
  2021-06-05 13:18 ` [PATCH 32/34] docs: userspace-api: landlock.rst: " Mauro Carvalho Chehab
@ 2021-06-05 13:18 ` Mauro Carvalho Chehab
  2021-06-05 13:18 ` [PATCH 34/34] docs: x86: " Mauro Carvalho Chehab
                   ` (2 subsequent siblings)
  35 siblings, 0 replies; 63+ 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, Christian Borntraeger, Claudio Imbrenda,
	Cornelia Huck, David Hildenbrand, Janosch Frank, Paolo Bonzini,
	kvm, 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/virt/kvm/s390-pv-boot.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/virt/kvm/s390-pv-boot.rst b/Documentation/virt/kvm/s390-pv-boot.rst
index ad1f7866c001..73a6083cb5e7 100644
--- a/Documentation/virt/kvm/s390-pv-boot.rst
+++ b/Documentation/virt/kvm/s390-pv-boot.rst
@@ -10,7 +10,7 @@ The memory of Protected Virtual Machines (PVMs) is not accessible to
 I/O or the hypervisor. In those cases where the hypervisor needs to
 access the memory of a PVM, that memory must be made accessible.
 Memory made accessible to the hypervisor will be encrypted. See
-:doc:`s390-pv` for details."
+Documentation/virt/kvm/s390-pv.rst for details."
 
 On IPL (boot) a small plaintext bootloader is started, which provides
 information about the encrypted components and necessary metadata to
-- 
2.31.1


^ permalink raw reply related	[flat|nested] 63+ messages in thread

* [PATCH 34/34] docs: x86: avoid using ReSt :doc:`foo` markup
  2021-06-05 13:17 [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag Mauro Carvalho Chehab
                   ` (32 preceding siblings ...)
  2021-06-05 13:18 ` [PATCH 33/34] docs: virt: kvm: s390-pv-boot.rst: " Mauro Carvalho Chehab
@ 2021-06-05 13:18 ` Mauro Carvalho Chehab
  2021-06-07 15:21   ` Peter Zijlstra
  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
  35 siblings, 1 reply; 63+ 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, H. Peter Anvin, Borislav Petkov,
	Ingo Molnar, Thomas Gleixner, linux-kernel, x86

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/x86/boot.rst | 4 ++--
 Documentation/x86/mtrr.rst | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/x86/boot.rst b/Documentation/x86/boot.rst
index fc844913dece..894a19897005 100644
--- a/Documentation/x86/boot.rst
+++ b/Documentation/x86/boot.rst
@@ -1343,7 +1343,7 @@ follow::
 In addition to read/modify/write the setup header of the struct
 boot_params as that of 16-bit boot protocol, the boot loader should
 also fill the additional fields of the struct boot_params as
-described in chapter :doc:`zero-page`.
+described in chapter Documentation/x86/zero-page.rst.
 
 After setting up the struct boot_params, the boot loader can load the
 32/64-bit kernel in the same way as that of 16-bit boot protocol.
@@ -1379,7 +1379,7 @@ can be calculated as follows::
 In addition to read/modify/write the setup header of the struct
 boot_params as that of 16-bit boot protocol, the boot loader should
 also fill the additional fields of the struct boot_params as described
-in chapter :doc:`zero-page`.
+in chapter Documentation/x86/zero-page.rst.
 
 After setting up the struct boot_params, the boot loader can load
 64-bit kernel in the same way as that of 16-bit boot protocol, but
diff --git a/Documentation/x86/mtrr.rst b/Documentation/x86/mtrr.rst
index c5b695d75349..9f0b1851771a 100644
--- a/Documentation/x86/mtrr.rst
+++ b/Documentation/x86/mtrr.rst
@@ -28,7 +28,7 @@ are aligned with platform MTRR setup. If MTRRs are only set up by the platform
 firmware code though and the OS does not make any specific MTRR mapping
 requests mtrr_type_lookup() should always return MTRR_TYPE_INVALID.
 
-For details refer to :doc:`pat`.
+For details refer to Documentation/x86/pat.rst.
 
 .. tip::
   On Intel P6 family processors (Pentium Pro, Pentium II and later)
-- 
2.31.1


^ permalink raw reply related	[flat|nested] 63+ 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
                   ` (33 preceding siblings ...)
  2021-06-05 13:18 ` [PATCH 34/34] docs: x86: " Mauro Carvalho Chehab
@ 2021-06-05 13:37 ` Mauro Carvalho Chehab
  2021-06-05 15:11 ` Nícolas F. R. A. Prado
  35 siblings, 0 replies; 63+ 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] 63+ messages in thread

* Re: [PATCH 19/34] docs: driver-api: surface_aggregator: avoid using ReSt :doc:`foo` markup
  2021-06-05 13:18 ` [PATCH 19/34] docs: driver-api: surface_aggregator: " Mauro Carvalho Chehab
@ 2021-06-05 14:14   ` Maximilian Luz
  2021-06-07  9:31     ` Hans de Goede
  0 siblings, 1 reply; 63+ messages in thread
From: Maximilian Luz @ 2021-06-05 14:14 UTC (permalink / raw)
  To: Mauro Carvalho Chehab, Jonathan Corbet, Linux Doc Mailing List
  Cc: Hans de Goede, linux-kernel

On 6/5/21 3:18 PM, 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>

Acked-by: Maximilian Luz <luzmaximilian@gmail.com>

> ---
>   .../surface_aggregator/clients/index.rst          |  3 ++-
>   .../driver-api/surface_aggregator/internal.rst    | 15 ++++++++-------
>   .../driver-api/surface_aggregator/overview.rst    |  6 ++++--
>   3 files changed, 14 insertions(+), 10 deletions(-)
> 
> diff --git a/Documentation/driver-api/surface_aggregator/clients/index.rst b/Documentation/driver-api/surface_aggregator/clients/index.rst
> index 98ea9946b8a2..30160513afa5 100644
> --- a/Documentation/driver-api/surface_aggregator/clients/index.rst
> +++ b/Documentation/driver-api/surface_aggregator/clients/index.rst
> @@ -5,7 +5,8 @@ Client Driver Documentation
>   ===========================
>   
>   This is the documentation for client drivers themselves. Refer to
> -:doc:`../client` for documentation on how to write client drivers.
> +Documentation/driver-api/surface_aggregator/client.rst for documentation
> +on how to write client drivers.
>   
>   .. toctree::
>      :maxdepth: 1
> diff --git a/Documentation/driver-api/surface_aggregator/internal.rst b/Documentation/driver-api/surface_aggregator/internal.rst
> index 72704734982a..8c7c80c9f418 100644
> --- a/Documentation/driver-api/surface_aggregator/internal.rst
> +++ b/Documentation/driver-api/surface_aggregator/internal.rst
> @@ -87,10 +87,11 @@ native SSAM devices, i.e. devices that are not defined in ACPI and not
>   implemented as platform devices, via |ssam_device| and |ssam_device_driver|
>   simplify management of client devices and client drivers.
>   
> -Refer to :doc:`client` for documentation regarding the client device/driver
> -API and interface options for other kernel drivers. It is recommended to
> -familiarize oneself with that chapter and the :doc:`ssh` before continuing
> -with the architectural overview below.
> +Refer to Documentation/driver-api/surface_aggregator/client.rst for
> +documentation regarding the client device/driver API and interface options
> +for other kernel drivers. It is recommended to familiarize oneself with
> +that chapter and the Documentation/driver-api/surface_aggregator/ssh.rst
> +before continuing with the architectural overview below.
>   
>   
>   Packet Transport Layer
> @@ -190,9 +191,9 @@ with success on the transmitter thread.
>   
>   Transmission of sequenced packets is limited by the number of concurrently
>   pending packets, i.e. a limit on how many packets may be waiting for an ACK
> -from the EC in parallel. This limit is currently set to one (see :doc:`ssh`
> -for the reasoning behind this). Control packets (i.e. ACK and NAK) can
> -always be transmitted.
> +from the EC in parallel. This limit is currently set to one (see
> +Documentation/driver-api/surface_aggregator/ssh.rst for the reasoning behind
> +this). Control packets (i.e. ACK and NAK) can always be transmitted.
>   
>   Receiver Thread
>   ---------------
> diff --git a/Documentation/driver-api/surface_aggregator/overview.rst b/Documentation/driver-api/surface_aggregator/overview.rst
> index 1e9d57e50063..26415e1ab7da 100644
> --- a/Documentation/driver-api/surface_aggregator/overview.rst
> +++ b/Documentation/driver-api/surface_aggregator/overview.rst
> @@ -73,5 +73,7 @@ being a direct response to a previous request. We may also refer to requests
>   without response as commands. In general, events need to be enabled via one
>   of multiple dedicated requests before they are sent by the EC.
>   
> -See :doc:`ssh` for a more technical protocol documentation and
> -:doc:`internal` for an overview of the internal driver architecture.
> +See Documentation/driver-api/surface_aggregator/ssh.rst for a
> +more technical protocol documentation and
> +Documentation/driver-api/surface_aggregator/internal.rst for an
> +overview of the internal driver architecture.
> 

^ permalink raw reply	[flat|nested] 63+ 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
                   ` (34 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
  35 siblings, 1 reply; 63+ 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] 63+ messages in thread

* Re: [PATCH 23/34] docs: i2c: avoid using ReSt :doc:`foo` markup
  2021-06-05 13:18 ` [PATCH 23/34] docs: i2c: " Mauro Carvalho Chehab
@ 2021-06-05 15:13   ` Wolfram Sang
  0 siblings, 0 replies; 63+ messages in thread
From: Wolfram Sang @ 2021-06-05 15:13 UTC (permalink / raw)
  To: Mauro Carvalho Chehab
  Cc: Jonathan Corbet, Linux Doc Mailing List, linux-i2c, linux-kernel

[-- Attachment #1: Type: text/plain, Size: 337 bytes --]

On Sat, Jun 05, 2021 at 03:18:22PM +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>

Thanks for doing this!

Acked-by: Wolfram Sang <wsa@kernel.org>


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

^ permalink raw reply	[flat|nested] 63+ 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; 63+ 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] 63+ messages in thread

* Re: [PATCH 13/34] docs: dev-tools: testing-overview.rst: avoid using ReSt :doc:`foo` markup
  2021-06-05 13:18 ` [PATCH 13/34] docs: dev-tools: testing-overview.rst: " Mauro Carvalho Chehab
@ 2021-06-05 15:43   ` David Gow
  2021-06-05 16:13     ` Mauro Carvalho Chehab
  0 siblings, 1 reply; 63+ 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, Daniel Latypov,
	Marco Elver, Linux Kernel Mailing List

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>
> ---

Hmm... I'd originally wanted this to read more like the name of the
tool than the path to the doc file, but given the :doc: prefix and
backticks are equally ugly, and no less confusing to the plain-text
reader than the filename, I'm happy to have this changed. Particularly
if we're standardising on this across the kernel documentation.

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


-- David

>  Documentation/dev-tools/testing-overview.rst | 16 ++++++++--------
>  1 file changed, 8 insertions(+), 8 deletions(-)
>
> diff --git a/Documentation/dev-tools/testing-overview.rst b/Documentation/dev-tools/testing-overview.rst
> index b5b46709969c..65feb81edb14 100644
> --- a/Documentation/dev-tools/testing-overview.rst
> +++ b/Documentation/dev-tools/testing-overview.rst
> @@ -71,15 +71,15 @@ can be used to verify that a test is executing particular functions or lines
>  of code. This is useful for determining how much of the kernel is being tested,
>  and for finding corner-cases which are not covered by the appropriate test.
>
> -:doc:`gcov` is GCC's coverage testing tool, which can be used with the kernel
> -to get global or per-module coverage. Unlike KCOV, it does not record per-task
> -coverage. Coverage data can be read from debugfs, and interpreted using the
> -usual gcov tooling.
> +Documentation/dev-tools/gcov.rst is GCC's coverage testing tool, which can be
> +used with the kernel to get global or per-module coverage. Unlike KCOV, it
> +does not record per-task coverage. Coverage data can be read from debugfs,
> +and interpreted using the usual gcov tooling.
>
> -:doc:`kcov` is a feature which can be built in to the kernel to allow
> -capturing coverage on a per-task level. It's therefore useful for fuzzing and
> -other situations where information about code executed during, for example, a
> -single syscall is useful.
> +Documentation/dev-tools/kcov.rst is a feature which can be built in to the
> +kernel to allow capturing coverage on a per-task level. It's therefore useful
> +for fuzzing and other situations where information about code executed during,
> +for example, a single syscall is useful.
>
>
>  Dynamic Analysis Tools
> --
> 2.31.1
>

^ permalink raw reply	[flat|nested] 63+ 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 " 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; 63+ 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] 63+ 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; 63+ 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] 63+ messages in thread

* Re: [PATCH 13/34] docs: dev-tools: testing-overview.rst: avoid using ReSt :doc:`foo` markup
  2021-06-05 15:43   ` David Gow
@ 2021-06-05 16:13     ` Mauro Carvalho Chehab
  0 siblings, 0 replies; 63+ messages in thread
From: Mauro Carvalho Chehab @ 2021-06-05 16:13 UTC (permalink / raw)
  To: David Gow
  Cc: Jonathan Corbet, Linux Doc Mailing List, Daniel Latypov,
	Marco Elver, Linux Kernel Mailing List

Em Sat, 5 Jun 2021 23:43:55 +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>
> > ---  
> 
> Hmm... I'd originally wanted this to read more like the name of the
> tool than the path to the doc file, but given the :doc: prefix and
> backticks are equally ugly, and no less confusing to the plain-text
> reader than the filename, I'm happy to have this changed. Particularly
> if we're standardising on this across the kernel documentation.

Yeah, the idea is to avoid :doc: treewide, at least for simple cases.

I'm proposing that we should still keep using:

	:doc:`some description <foo>`

for named references, which is still ugly in plain-text, but can be
used to provide a better hyperlink when the docs are converted
into html/LaTeX/pdf, as it would be converted (in html) as:

	<a href="foo.html">some description</a>

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

Thanks!
Mauro

> 
> 
> -- David
> 
> >  Documentation/dev-tools/testing-overview.rst | 16 ++++++++--------
> >  1 file changed, 8 insertions(+), 8 deletions(-)
> >
> > diff --git a/Documentation/dev-tools/testing-overview.rst b/Documentation/dev-tools/testing-overview.rst
> > index b5b46709969c..65feb81edb14 100644
> > --- a/Documentation/dev-tools/testing-overview.rst
> > +++ b/Documentation/dev-tools/testing-overview.rst
> > @@ -71,15 +71,15 @@ can be used to verify that a test is executing particular functions or lines
> >  of code. This is useful for determining how much of the kernel is being tested,
> >  and for finding corner-cases which are not covered by the appropriate test.
> >
> > -:doc:`gcov` is GCC's coverage testing tool, which can be used with the kernel
> > -to get global or per-module coverage. Unlike KCOV, it does not record per-task
> > -coverage. Coverage data can be read from debugfs, and interpreted using the
> > -usual gcov tooling.
> > +Documentation/dev-tools/gcov.rst is GCC's coverage testing tool, which can be
> > +used with the kernel to get global or per-module coverage. Unlike KCOV, it
> > +does not record per-task coverage. Coverage data can be read from debugfs,
> > +and interpreted using the usual gcov tooling.
> >
> > -:doc:`kcov` is a feature which can be built in to the kernel to allow
> > -capturing coverage on a per-task level. It's therefore useful for fuzzing and
> > -other situations where information about code executed during, for example, a
> > -single syscall is useful.
> > +Documentation/dev-tools/kcov.rst is a feature which can be built in to the
> > +kernel to allow capturing coverage on a per-task level. It's therefore useful
> > +for fuzzing and other situations where information about code executed during,
> > +for example, a single syscall is useful.
> >
> >
> >  Dynamic Analysis Tools
> > --
> > 2.31.1
> >  



Thanks,
Mauro

^ permalink raw reply	[flat|nested] 63+ messages in thread

* Re: [PATCH 18/34] docs: driver-api: gpio: using-gpio.rst: avoid using ReSt :doc:`foo` markup
  2021-06-05 13:18 ` [PATCH 18/34] docs: driver-api: gpio: using-gpio.rst: " Mauro Carvalho Chehab
@ 2021-06-05 16:25   ` Linus Walleij
  0 siblings, 0 replies; 63+ messages in thread
From: Linus Walleij @ 2021-06-05 16:25 UTC (permalink / raw)
  To: Mauro Carvalho Chehab
  Cc: Jonathan Corbet, Linux Doc Mailing List, Bartosz Golaszewski,
	open list:GPIO SUBSYSTEM, linux-kernel

On Sat, Jun 5, 2021 at 3: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>

Reviewed-by: Linus Walleij <linus.walleij@linaro.org>

Yours,
Linus Walleij

^ permalink raw reply	[flat|nested] 63+ 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; 63+ 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] 63+ messages in thread

* Re: [PATCH 22/34] docs: hwmon: adm1177.rst: avoid using ReSt :doc:`foo` markup
  2021-06-05 13:18 ` [PATCH 22/34] docs: hwmon: adm1177.rst: " Mauro Carvalho Chehab
@ 2021-06-06 13:01   ` Guenter Roeck
  0 siblings, 0 replies; 63+ messages in thread
From: Guenter Roeck @ 2021-06-06 13:01 UTC (permalink / raw)
  To: Mauro Carvalho Chehab
  Cc: Jonathan Corbet, Linux Doc Mailing List, Jean Delvare,
	linux-hwmon, linux-kernel

On Sat, Jun 05, 2021 at 03:18:21PM +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>

Applied.

Thanks,
Guenter

> ---
>  Documentation/hwmon/adm1177.rst | 3 ++-
>  1 file changed, 2 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/hwmon/adm1177.rst b/Documentation/hwmon/adm1177.rst
> index 471be1e98d6f..1c85a2af92bf 100644
> --- a/Documentation/hwmon/adm1177.rst
> +++ b/Documentation/hwmon/adm1177.rst
> @@ -20,7 +20,8 @@ Usage Notes
>  -----------
>  
>  This driver does not auto-detect devices. You will have to instantiate the
> -devices explicitly. Please see :doc:`/i2c/instantiating-devices` for details.
> +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst
> +for details.
>  
>  
>  Sysfs entries

^ permalink raw reply	[flat|nested] 63+ 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; 63+ 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] 63+ 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; 63+ 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] 63+ messages in thread

* Re: [PATCH 19/34] docs: driver-api: surface_aggregator: avoid using ReSt :doc:`foo` markup
  2021-06-05 14:14   ` Maximilian Luz
@ 2021-06-07  9:31     ` Hans de Goede
  2021-06-07  9:55       ` Mauro Carvalho Chehab
  0 siblings, 1 reply; 63+ messages in thread
From: Hans de Goede @ 2021-06-07  9:31 UTC (permalink / raw)
  To: Maximilian Luz, Mauro Carvalho Chehab, Jonathan Corbet,
	Linux Doc Mailing List
  Cc: linux-kernel

Hi,

On 6/5/21 4:14 PM, Maximilian Luz wrote:
> On 6/5/21 3:18 PM, 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>
> 
> Acked-by: Maximilian Luz <luzmaximilian@gmail.com>

Mauro, I assume that you are going to take care of sending this
to Linus, or do you want me to merge this patch into the pdx86 tree?

Regards,

Hans


> 
>> ---
>>   .../surface_aggregator/clients/index.rst          |  3 ++-
>>   .../driver-api/surface_aggregator/internal.rst    | 15 ++++++++-------
>>   .../driver-api/surface_aggregator/overview.rst    |  6 ++++--
>>   3 files changed, 14 insertions(+), 10 deletions(-)
>>
>> diff --git a/Documentation/driver-api/surface_aggregator/clients/index.rst b/Documentation/driver-api/surface_aggregator/clients/index.rst
>> index 98ea9946b8a2..30160513afa5 100644
>> --- a/Documentation/driver-api/surface_aggregator/clients/index.rst
>> +++ b/Documentation/driver-api/surface_aggregator/clients/index.rst
>> @@ -5,7 +5,8 @@ Client Driver Documentation
>>   ===========================
>>     This is the documentation for client drivers themselves. Refer to
>> -:doc:`../client` for documentation on how to write client drivers.
>> +Documentation/driver-api/surface_aggregator/client.rst for documentation
>> +on how to write client drivers.
>>     .. toctree::
>>      :maxdepth: 1
>> diff --git a/Documentation/driver-api/surface_aggregator/internal.rst b/Documentation/driver-api/surface_aggregator/internal.rst
>> index 72704734982a..8c7c80c9f418 100644
>> --- a/Documentation/driver-api/surface_aggregator/internal.rst
>> +++ b/Documentation/driver-api/surface_aggregator/internal.rst
>> @@ -87,10 +87,11 @@ native SSAM devices, i.e. devices that are not defined in ACPI and not
>>   implemented as platform devices, via |ssam_device| and |ssam_device_driver|
>>   simplify management of client devices and client drivers.
>>   -Refer to :doc:`client` for documentation regarding the client device/driver
>> -API and interface options for other kernel drivers. It is recommended to
>> -familiarize oneself with that chapter and the :doc:`ssh` before continuing
>> -with the architectural overview below.
>> +Refer to Documentation/driver-api/surface_aggregator/client.rst for
>> +documentation regarding the client device/driver API and interface options
>> +for other kernel drivers. It is recommended to familiarize oneself with
>> +that chapter and the Documentation/driver-api/surface_aggregator/ssh.rst
>> +before continuing with the architectural overview below.
>>       Packet Transport Layer
>> @@ -190,9 +191,9 @@ with success on the transmitter thread.
>>     Transmission of sequenced packets is limited by the number of concurrently
>>   pending packets, i.e. a limit on how many packets may be waiting for an ACK
>> -from the EC in parallel. This limit is currently set to one (see :doc:`ssh`
>> -for the reasoning behind this). Control packets (i.e. ACK and NAK) can
>> -always be transmitted.
>> +from the EC in parallel. This limit is currently set to one (see
>> +Documentation/driver-api/surface_aggregator/ssh.rst for the reasoning behind
>> +this). Control packets (i.e. ACK and NAK) can always be transmitted.
>>     Receiver Thread
>>   ---------------
>> diff --git a/Documentation/driver-api/surface_aggregator/overview.rst b/Documentation/driver-api/surface_aggregator/overview.rst
>> index 1e9d57e50063..26415e1ab7da 100644
>> --- a/Documentation/driver-api/surface_aggregator/overview.rst
>> +++ b/Documentation/driver-api/surface_aggregator/overview.rst
>> @@ -73,5 +73,7 @@ being a direct response to a previous request. We may also refer to requests
>>   without response as commands. In general, events need to be enabled via one
>>   of multiple dedicated requests before they are sent by the EC.
>>   -See :doc:`ssh` for a more technical protocol documentation and
>> -:doc:`internal` for an overview of the internal driver architecture.
>> +See Documentation/driver-api/surface_aggregator/ssh.rst for a
>> +more technical protocol documentation and
>> +Documentation/driver-api/surface_aggregator/internal.rst for an
>> +overview of the internal driver architecture.
>>
> 


^ permalink raw reply	[flat|nested] 63+ messages in thread

* Re: [PATCH 19/34] docs: driver-api: surface_aggregator: avoid using ReSt :doc:`foo` markup
  2021-06-07  9:31     ` Hans de Goede
@ 2021-06-07  9:55       ` Mauro Carvalho Chehab
  2021-06-07 10:07         ` Hans de Goede
  0 siblings, 1 reply; 63+ messages in thread
From: Mauro Carvalho Chehab @ 2021-06-07  9:55 UTC (permalink / raw)
  To: Hans de Goede, Jonathan Corbet
  Cc: Maximilian Luz, Linux Doc Mailing List, linux-kernel

Hi Hans,

Em Mon, 7 Jun 2021 11:31:49 +0200
Hans de Goede <hdegoede@redhat.com> escreveu:

> Hi,
> 
> On 6/5/21 4:14 PM, Maximilian Luz wrote:
> > On 6/5/21 3:18 PM, 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>  
> > 
> > Acked-by: Maximilian Luz <luzmaximilian@gmail.com>  
> 
> Mauro, I assume that you are going to take care of sending this
> to Linus, or do you want me to merge this patch into the pdx86 tree?

Whatever works best for you and Jon, as it should either be merged
via each maintainers' tree or at the docs tree ;-)

Regards,
Mauro

^ permalink raw reply	[flat|nested] 63+ messages in thread

* Re: [PATCH 19/34] docs: driver-api: surface_aggregator: avoid using ReSt :doc:`foo` markup
  2021-06-07  9:55       ` Mauro Carvalho Chehab
@ 2021-06-07 10:07         ` Hans de Goede
  0 siblings, 0 replies; 63+ messages in thread
From: Hans de Goede @ 2021-06-07 10:07 UTC (permalink / raw)
  To: Mauro Carvalho Chehab, Jonathan Corbet
  Cc: Maximilian Luz, Linux Doc Mailing List, linux-kernel

Hi,

On 6/7/21 11:55 AM, Mauro Carvalho Chehab wrote:
> Hi Hans,
> 
> Em Mon, 7 Jun 2021 11:31:49 +0200
> Hans de Goede <hdegoede@redhat.com> escreveu:
> 
>> Hi,
>>
>> On 6/5/21 4:14 PM, Maximilian Luz wrote:
>>> On 6/5/21 3:18 PM, 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>  
>>>
>>> Acked-by: Maximilian Luz <luzmaximilian@gmail.com>  
>>
>> Mauro, I assume that you are going to take care of sending this
>> to Linus, or do you want me to merge this patch into the pdx86 tree?
> 
> Whatever works best for you and Jon, as it should either be merged
> via each maintainers' tree or at the docs tree ;-)

I think it is probably easiest if Jon just picks up the entire series.

Jon, please let me know if you want me to merge this patch.

Regards,

Hans


^ permalink raw reply	[flat|nested] 63+ messages in thread

* Re: [PATCH 34/34] docs: x86: avoid using ReSt :doc:`foo` markup
  2021-06-05 13:18 ` [PATCH 34/34] docs: x86: " Mauro Carvalho Chehab
@ 2021-06-07 15:21   ` Peter Zijlstra
  0 siblings, 0 replies; 63+ messages in thread
From: Peter Zijlstra @ 2021-06-07 15:21 UTC (permalink / raw)
  To: Mauro Carvalho Chehab
  Cc: Jonathan Corbet, Linux Doc Mailing List, H. Peter Anvin,
	Borislav Petkov, Ingo Molnar, Thomas Gleixner, linux-kernel, x86

On Sat, Jun 05, 2021 at 03:18:33PM +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>

Thanks!

Acked-by: Peter Zijlstra (Intel) <peterz@infradead.org>

> ---
>  Documentation/x86/boot.rst | 4 ++--
>  Documentation/x86/mtrr.rst | 2 +-
>  2 files changed, 3 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/x86/boot.rst b/Documentation/x86/boot.rst
> index fc844913dece..894a19897005 100644
> --- a/Documentation/x86/boot.rst
> +++ b/Documentation/x86/boot.rst
> @@ -1343,7 +1343,7 @@ follow::
>  In addition to read/modify/write the setup header of the struct
>  boot_params as that of 16-bit boot protocol, the boot loader should
>  also fill the additional fields of the struct boot_params as
> -described in chapter :doc:`zero-page`.
> +described in chapter Documentation/x86/zero-page.rst.
>  
>  After setting up the struct boot_params, the boot loader can load the
>  32/64-bit kernel in the same way as that of 16-bit boot protocol.
> @@ -1379,7 +1379,7 @@ can be calculated as follows::
>  In addition to read/modify/write the setup header of the struct
>  boot_params as that of 16-bit boot protocol, the boot loader should
>  also fill the additional fields of the struct boot_params as described
> -in chapter :doc:`zero-page`.
> +in chapter Documentation/x86/zero-page.rst.
>  
>  After setting up the struct boot_params, the boot loader can load
>  64-bit kernel in the same way as that of 16-bit boot protocol, but
> diff --git a/Documentation/x86/mtrr.rst b/Documentation/x86/mtrr.rst
> index c5b695d75349..9f0b1851771a 100644
> --- a/Documentation/x86/mtrr.rst
> +++ b/Documentation/x86/mtrr.rst
> @@ -28,7 +28,7 @@ are aligned with platform MTRR setup. If MTRRs are only set up by the platform
>  firmware code though and the OS does not make any specific MTRR mapping
>  requests mtrr_type_lookup() should always return MTRR_TYPE_INVALID.
>  
> -For details refer to :doc:`pat`.
> +For details refer to Documentation/x86/pat.rst.
>  
>  .. tip::
>    On Intel P6 family processors (Pentium Pro, Pentium II and later)
> -- 
> 2.31.1
> 

^ permalink raw reply	[flat|nested] 63+ 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; 63+ 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] 63+ 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 " Mauro Carvalho Chehab
  2021-06-05 15:44   ` David Gow
@ 2021-06-07 20:20   ` Brendan Higgins
  1 sibling, 0 replies; 63+ 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] 63+ 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; 63+ 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] 63+ 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; 63+ 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] 63+ messages in thread

* Re: [PATCH 30/34] docs: trace: coresight: coresight.rst: avoid using ReSt :doc:`foo` markup
  2021-06-05 13:18 ` [PATCH 30/34] docs: trace: coresight: coresight.rst: " Mauro Carvalho Chehab
@ 2021-06-08 15:23   ` Mathieu Poirier
  0 siblings, 0 replies; 63+ messages in thread
From: Mathieu Poirier @ 2021-06-08 15:23 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 Sat, Jun 05, 2021 at 03:18:29PM +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
> 

^ permalink raw reply	[flat|nested] 63+ messages in thread

* Re: [PATCH 26/34] docs: PCI: endpoint: pci-endpoint-cfs.rst: avoid using ReSt :doc:`foo` markup
  2021-06-05 13:18 ` [PATCH 26/34] docs: PCI: endpoint: pci-endpoint-cfs.rst: " Mauro Carvalho Chehab
@ 2021-06-10 23:46   ` Bjorn Helgaas
  2021-06-11  8:45     ` Mauro Carvalho Chehab
  0 siblings, 1 reply; 63+ messages in thread
From: Bjorn Helgaas @ 2021-06-10 23:46 UTC (permalink / raw)
  To: Mauro Carvalho Chehab
  Cc: Jonathan Corbet, Linux Doc Mailing List, Bjorn Helgaas,
	Kishon Vijay Abraham I, Lorenzo Pieralisi, linux-kernel,
	linux-pci

On Sat, Jun 05, 2021 at 03:18:25PM +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>

It'd be nice to know why we're doing this and what the benefit is.

Maybe if you know more about ReSt, it's obvious that using :doc:`foo`
is wrong and produces the wrong output or something.  But I don't
know.

I do think the pathname in the new text is easier for plain-text
readers to follow.

(What's the correct spelling of "ReSt", BTW?  The cover letter has
"ReST", this patch has "ReSt", wikipedia says "RST, ReST, or reST".)

But anyway,

Acked-by: Bjorn Helgaas <bhelgaas@google.com>

> ---
>  Documentation/PCI/endpoint/pci-endpoint-cfs.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/Documentation/PCI/endpoint/pci-endpoint-cfs.rst b/Documentation/PCI/endpoint/pci-endpoint-cfs.rst
> index 696f8eeb4738..db609b97ad58 100644
> --- a/Documentation/PCI/endpoint/pci-endpoint-cfs.rst
> +++ b/Documentation/PCI/endpoint/pci-endpoint-cfs.rst
> @@ -125,4 +125,4 @@ all the EPF devices are created and linked with the EPC device.
>  						| interrupt_pin
>  						| function
>  
> -[1] :doc:`pci-endpoint`
> +[1] Documentation/PCI/endpoint/pci-endpoint.rst
> -- 
> 2.31.1
> 

^ permalink raw reply	[flat|nested] 63+ messages in thread

* Re: [PATCH 27/34] docs: PCI: pci.rst: avoid using ReSt :doc:`foo` markup
  2021-06-05 13:18 ` [PATCH 27/34] docs: PCI: pci.rst: " Mauro Carvalho Chehab
@ 2021-06-10 23:46   ` Bjorn Helgaas
  0 siblings, 0 replies; 63+ messages in thread
From: Bjorn Helgaas @ 2021-06-10 23:46 UTC (permalink / raw)
  To: Mauro Carvalho Chehab
  Cc: Jonathan Corbet, Linux Doc Mailing List, Bjorn Helgaas,
	linux-kernel, linux-pci

On Sat, Jun 05, 2021 at 03:18:26PM +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>

Acked-by: Bjorn Helgaas <bhelgaas@google.com>

> ---
>  Documentation/PCI/pci.rst | 6 +++---
>  1 file changed, 3 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/PCI/pci.rst b/Documentation/PCI/pci.rst
> index 814b40f8360b..fa651e25d98c 100644
> --- a/Documentation/PCI/pci.rst
> +++ b/Documentation/PCI/pci.rst
> @@ -265,7 +265,7 @@ Set the DMA mask size
>  ---------------------
>  .. note::
>     If anything below doesn't make sense, please refer to
> -   :doc:`/core-api/dma-api`. This section is just a reminder that
> +   Documentation/core-api/dma-api.rst. This section is just a reminder that
>     drivers need to indicate DMA capabilities of the device and is not
>     an authoritative source for DMA interfaces.
>  
> @@ -291,7 +291,7 @@ Many 64-bit "PCI" devices (before PCI-X) and some PCI-X devices are
>  Setup shared control data
>  -------------------------
>  Once the DMA masks are set, the driver can allocate "consistent" (a.k.a. shared)
> -memory.  See :doc:`/core-api/dma-api` for a full description of
> +memory.  See Documentation/core-api/dma-api.rst for a full description of
>  the DMA APIs. This section is just a reminder that it needs to be done
>  before enabling DMA on the device.
>  
> @@ -421,7 +421,7 @@ owners if there is one.
>  
>  Then clean up "consistent" buffers which contain the control data.
>  
> -See :doc:`/core-api/dma-api` for details on unmapping interfaces.
> +See Documentation/core-api/dma-api.rst for details on unmapping interfaces.
>  
>  
>  Unregister from other subsystems
> -- 
> 2.31.1
> 

^ permalink raw reply	[flat|nested] 63+ messages in thread

* Re: [PATCH 26/34] docs: PCI: endpoint: pci-endpoint-cfs.rst: avoid using ReSt :doc:`foo` markup
  2021-06-10 23:46   ` Bjorn Helgaas
@ 2021-06-11  8:45     ` Mauro Carvalho Chehab
  0 siblings, 0 replies; 63+ messages in thread
From: Mauro Carvalho Chehab @ 2021-06-11  8:45 UTC (permalink / raw)
  To: Bjorn Helgaas
  Cc: Jonathan Corbet, Linux Doc Mailing List, Bjorn Helgaas,
	Kishon Vijay Abraham I, Lorenzo Pieralisi, linux-kernel,
	linux-pci

Em Thu, 10 Jun 2021 18:46:22 -0500
Bjorn Helgaas <helgaas@kernel.org> escreveu:

> On Sat, Jun 05, 2021 at 03:18:25PM +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>  
> 
> It'd be nice to know why we're doing this and what the benefit is.

That came from an upstream discussion, mentioned on patch 00/34:

		https://lore.kernel.org/linux-doc/871r9k6rmy.fsf@meer.lwn.net/

Basically, using Documentation/.../foo.rst allows some text editors
to navigate directly to the file. Also, there's a preference from
some maintainers to keep the ReST files as close as possible to plain
text.

> Maybe if you know more about ReSt, it's obvious that using :doc:`foo`
> is wrong and produces the wrong output or something.  But I don't
> know.

It is more a matter of preference. That's said, there is indeed
an issue with the current builder: when using SPHINXDIRS="book",
doc:`foo` references may not work well. For instance, if one is
building just the driver-api book, a reference like :doc:`../admin-guide/foo`
can't be solved and will produce a warning, plus a bad output.

By using Documentation/admin-guide/foo.rst, it will simply be
displayed as a text without producing any harm.

We discussed in the past about that, but we didn't reach to any
conclusion about the proper way to fix it.

> I do think the pathname in the new text is easier for plain-text
> readers to follow.

Yes.

> 
> (What's the correct spelling of "ReSt", BTW?  The cover letter has
> "ReST", this patch has "ReSt", wikipedia says "RST, ReST, or reST".)

ReSt was a typo.. sorry for that. I guess the proper way is ReST,
but several places use RST instead. For instance, the conversion
tool pandoc uses "rst" to refer to this format.

> 
> But anyway,
> 
> Acked-by: Bjorn Helgaas <bhelgaas@google.com>

Thanks!
Mauro

> 
> > ---
> >  Documentation/PCI/endpoint/pci-endpoint-cfs.rst | 2 +-
> >  1 file changed, 1 insertion(+), 1 deletion(-)
> > 
> > diff --git a/Documentation/PCI/endpoint/pci-endpoint-cfs.rst b/Documentation/PCI/endpoint/pci-endpoint-cfs.rst
> > index 696f8eeb4738..db609b97ad58 100644
> > --- a/Documentation/PCI/endpoint/pci-endpoint-cfs.rst
> > +++ b/Documentation/PCI/endpoint/pci-endpoint-cfs.rst
> > @@ -125,4 +125,4 @@ all the EPF devices are created and linked with the EPC device.
> >  						| interrupt_pin
> >  						| function
> >  
> > -[1] :doc:`pci-endpoint`
> > +[1] Documentation/PCI/endpoint/pci-endpoint.rst
> > -- 
> > 2.31.1
> >   



Thanks,
Mauro

^ permalink raw reply	[flat|nested] 63+ 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; 63+ 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] 63+ 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; 63+ 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] 63+ messages in thread

end of thread, other threads:[~2021-06-16  6:13 UTC | newest]

Thread overview: 63+ 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 01/34] docs: devices.rst: better reference documentation docs 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 03/34] media: docs: */media/index.rst: don't use ReST doc:`foo` Mauro Carvalho Chehab
2021-06-05 13:18 ` [PATCH 04/34] media: userspace-api: avoid using ReST :doc:`foo` markup Mauro Carvalho Chehab
2021-06-05 13:18 ` [PATCH 05/34] media: driver-api: drivers: " Mauro Carvalho Chehab
2021-06-05 13:18 ` [PATCH 06/34] media: admin-guide: " Mauro Carvalho Chehab
2021-06-05 13:18 ` [PATCH 07/34] docs: admin-guide: pm: avoid using ReSt " Mauro Carvalho Chehab
2021-06-05 13:18 ` [PATCH 08/34] docs: admin-guide: hw-vuln: avoid using ReST " Mauro Carvalho Chehab
2021-06-05 13:18 ` [PATCH 09/34] docs: admin-guide: sysctl: " Mauro Carvalho Chehab
2021-06-05 13:18 ` [PATCH 10/34] docs: block: biodoc.rst: avoid using ReSt " Mauro Carvalho Chehab
2021-06-05 13:18 ` [PATCH 11/34] docs: bpf: bpf_lsm.rst: " Mauro Carvalho Chehab
2021-06-05 13:18 ` [PATCH 12/34] docs: core-api: " Mauro Carvalho Chehab
2021-06-05 13:18 ` [PATCH 13/34] docs: dev-tools: testing-overview.rst: " Mauro Carvalho Chehab
2021-06-05 15:43   ` David Gow
2021-06-05 16:13     ` Mauro Carvalho Chehab
2021-06-05 13:18 ` [PATCH 14/34] docs: dev-tools: kunit: avoid using ReST " 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:18 ` [PATCH 15/34] docs: devicetree: bindings: submitting-patches.rst: avoid using ReSt " Mauro Carvalho Chehab
2021-06-05 13:18 ` [PATCH 16/34] docs: doc-guide: " Mauro Carvalho Chehab
2021-06-05 13:18 ` [PATCH 17/34] docs: driver-api: " Mauro Carvalho Chehab
2021-06-05 13:18 ` [PATCH 18/34] docs: driver-api: gpio: using-gpio.rst: " Mauro Carvalho Chehab
2021-06-05 16:25   ` Linus Walleij
2021-06-05 13:18 ` [PATCH 19/34] docs: driver-api: surface_aggregator: " Mauro Carvalho Chehab
2021-06-05 14:14   ` Maximilian Luz
2021-06-07  9:31     ` Hans de Goede
2021-06-07  9:55       ` Mauro Carvalho Chehab
2021-06-07 10:07         ` Hans de Goede
2021-06-05 13:18 ` [PATCH 20/34] docs: driver-api: usb: " Mauro Carvalho Chehab
2021-06-05 13:18 ` [PATCH 21/34] docs: firmware-guide: acpi: " Mauro Carvalho Chehab
2021-06-05 13:18 ` [PATCH 22/34] docs: hwmon: adm1177.rst: " Mauro Carvalho Chehab
2021-06-06 13:01   ` Guenter Roeck
2021-06-05 13:18 ` [PATCH 23/34] docs: i2c: " Mauro Carvalho Chehab
2021-06-05 15:13   ` Wolfram Sang
2021-06-05 13:18 ` [PATCH 24/34] docs: kernel-hacking: hacking.rst: " Mauro Carvalho Chehab
2021-06-05 13:18 ` [PATCH 25/34] docs: networking: devlink: " Mauro Carvalho Chehab
2021-06-05 13:18 ` [PATCH 26/34] docs: PCI: endpoint: pci-endpoint-cfs.rst: " Mauro Carvalho Chehab
2021-06-10 23:46   ` Bjorn Helgaas
2021-06-11  8:45     ` Mauro Carvalho Chehab
2021-06-05 13:18 ` [PATCH 27/34] docs: PCI: pci.rst: " Mauro Carvalho Chehab
2021-06-10 23:46   ` Bjorn Helgaas
2021-06-05 13:18 ` [PATCH 28/34] docs: process: submitting-patches.rst: " Mauro Carvalho Chehab
2021-06-05 13:18 ` [PATCH 29/34] docs: security: landlock.rst: " Mauro Carvalho Chehab
2021-06-05 13:18 ` [PATCH 30/34] docs: trace: coresight: coresight.rst: " Mauro Carvalho Chehab
2021-06-08 15:23   ` Mathieu Poirier
2021-06-05 13:18 ` [PATCH 31/34] docs: trace: ftrace.rst: " Mauro Carvalho Chehab
2021-06-05 13:18 ` [PATCH 32/34] docs: userspace-api: landlock.rst: " Mauro Carvalho Chehab
2021-06-05 13:18 ` [PATCH 33/34] docs: virt: kvm: s390-pv-boot.rst: " Mauro Carvalho Chehab
2021-06-05 13:18 ` [PATCH 34/34] docs: x86: " Mauro Carvalho Chehab
2021-06-07 15:21   ` Peter Zijlstra
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).