[PATCH v2 00/29] docs: avoid using ReST :doc:`foo` tag

[PATCH v2 00/29] docs: avoid using ReST :doc:`foo` tag

[Mauro Carvalho Chehab]

(Maintainers bcc, to avoid too many recipient troubles)

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

It is better to avoid using :doc:`foo` to refer to Documentation/foo.rst, as the
automarkup.py extension should handle it automatically, on most cases.

There are a couple of exceptions to this rule:

1. when :doc:  tag is used to point to a kernel-doc DOC: markup;
2. when it is used with a named tag, e. g. :doc:`some name <foo>`;

On this series:

Patch 1 manually adjust the references inside driver-api/pm/devices.rst,
as there it uses :file:`foo` to refer to some Documentation/ files;

Patch 2 converts a table at Documentation/dev-tools/kunit/api/index.rst
into a list, carefully avoiding the 

The remaining patches convert the other occurrences via a replace script.
They were manually edited, in order to honour 80-columns where possible.

This series based on docs-next branch. In order to avoid merge conflicts,
I rebased it internally against yesterday's linux-next, dropping a patch
and a hunk that would have caused conflicts there.

I'll re-send the remaining patch (plus another patch) with conflicting
changes, together with any other doc:`filename` reference that might
still be upstream by 5.14-rc1.

---

v2:
   - dropped media patches (as I merged via my own tree);
   - removed one patch that would conflict at linux-next (adm1177.rst);
   - removed one hunk fron kunit patch that would also conflict at
     linux-next.

Mauro Carvalho Chehab (29):
  docs: devices.rst: better reference documentation docs
  docs: dev-tools: kunit: don't use a table for docs name
  docs: admin-guide: pm: avoid using ReST :doc:`foo` markup
  docs: admin-guide: hw-vuln: avoid using ReST :doc:`foo` markup
  docs: admin-guide: sysctl: avoid using ReST :doc:`foo` markup
  docs: block: biodoc.rst: avoid using ReST :doc:`foo` markup
  docs: bpf: bpf_lsm.rst: avoid using ReST :doc:`foo` markup
  docs: core-api: avoid using ReST :doc:`foo` markup
  docs: dev-tools: testing-overview.rst: avoid using ReST :doc:`foo`
    markup
  docs: dev-tools: kunit: avoid using ReST :doc:`foo` markup
  docs: devicetree: bindings: submitting-patches.rst: avoid using ReST
    :doc:`foo` markup
  docs: doc-guide: avoid using ReST :doc:`foo` markup
  docs: driver-api: avoid using ReST :doc:`foo` markup
  docs: driver-api: gpio: using-gpio.rst: avoid using ReST :doc:`foo`
    markup
  docs: driver-api: surface_aggregator: avoid using ReST :doc:`foo`
    markup
  docs: driver-api: usb: avoid using ReST :doc:`foo` markup
  docs: firmware-guide: acpi: avoid using ReST :doc:`foo` markup
  docs: i2c: avoid using ReST :doc:`foo` markup
  docs: kernel-hacking: hacking.rst: avoid using ReST :doc:`foo` markup
  docs: networking: devlink: avoid using ReST :doc:`foo` markup
  docs: PCI: endpoint: pci-endpoint-cfs.rst: avoid using ReST :doc:`foo`
    markup
  docs: PCI: pci.rst: avoid using ReST :doc:`foo` markup
  docs: process: submitting-patches.rst: avoid using ReST :doc:`foo`
    markup
  docs: security: landlock.rst: avoid using ReST :doc:`foo` markup
  docs: trace: coresight: coresight.rst: avoid using ReST :doc:`foo`
    markup
  docs: trace: ftrace.rst: avoid using ReST :doc:`foo` markup
  docs: userspace-api: landlock.rst: avoid using ReST :doc:`foo` markup
  docs: virt: kvm: s390-pv-boot.rst: avoid using ReST :doc:`foo` markup
  docs: x86: avoid using ReST :doc:`foo` markup

 .../PCI/endpoint/pci-endpoint-cfs.rst         |  2 +-
 Documentation/PCI/pci.rst                     |  6 +--
 .../special-register-buffer-data-sampling.rst |  3 +-
 Documentation/admin-guide/pm/intel_idle.rst   | 16 +++++---
 Documentation/admin-guide/pm/intel_pstate.rst |  9 +++--
 Documentation/admin-guide/sysctl/abi.rst      |  2 +-
 Documentation/admin-guide/sysctl/kernel.rst   | 37 ++++++++++---------
 Documentation/block/biodoc.rst                |  2 +-
 Documentation/bpf/bpf_lsm.rst                 | 13 ++++---
 .../core-api/bus-virt-phys-mapping.rst        |  2 +-
 Documentation/core-api/dma-api.rst            |  5 ++-
 Documentation/core-api/dma-isa-lpc.rst        |  2 +-
 Documentation/core-api/index.rst              |  4 +-
 Documentation/dev-tools/kunit/api/index.rst   |  8 ++--
 Documentation/dev-tools/kunit/faq.rst         |  2 +-
 Documentation/dev-tools/kunit/index.rst       | 14 +++----
 Documentation/dev-tools/kunit/start.rst       |  4 +-
 Documentation/dev-tools/kunit/tips.rst        |  5 ++-
 Documentation/dev-tools/kunit/usage.rst       |  8 ++--
 Documentation/dev-tools/testing-overview.rst  | 16 ++++----
 .../bindings/submitting-patches.rst           | 11 +++---
 Documentation/doc-guide/contributing.rst      |  8 ++--
 Documentation/driver-api/gpio/using-gpio.rst  |  4 +-
 Documentation/driver-api/ioctl.rst            |  2 +-
 Documentation/driver-api/pm/devices.rst       |  8 ++--
 .../surface_aggregator/clients/index.rst      |  3 +-
 .../surface_aggregator/internal.rst           | 15 ++++----
 .../surface_aggregator/overview.rst           |  6 ++-
 Documentation/driver-api/usb/dma.rst          |  6 +--
 .../acpi/dsd/data-node-references.rst         |  3 +-
 .../firmware-guide/acpi/dsd/graph.rst         |  2 +-
 .../firmware-guide/acpi/enumeration.rst       |  7 ++--
 Documentation/i2c/instantiating-devices.rst   |  2 +-
 Documentation/i2c/old-module-parameters.rst   |  3 +-
 Documentation/i2c/smbus-protocol.rst          |  4 +-
 Documentation/kernel-hacking/hacking.rst      |  4 +-
 .../networking/devlink/devlink-region.rst     |  2 +-
 .../networking/devlink/devlink-trap.rst       |  4 +-
 Documentation/process/submitting-patches.rst  | 32 ++++++++--------
 Documentation/security/landlock.rst           |  3 +-
 Documentation/trace/coresight/coresight.rst   |  8 ++--
 Documentation/trace/ftrace.rst                |  2 +-
 Documentation/userspace-api/landlock.rst      | 11 +++---
 Documentation/virt/kvm/s390-pv-boot.rst       |  2 +-
 Documentation/x86/boot.rst                    |  4 +-
 Documentation/x86/mtrr.rst                    |  2 +-
 46 files changed, 171 insertions(+), 147 deletions(-)

-- 
2.31.1

[PATCH v2 11/29] docs: devicetree: bindings: submitting-patches.rst: avoid using ReST :doc:`foo` markup

[Mauro Carvalho Chehab]

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

Re: [PATCH v2 11/29] docs: devicetree: bindings: submitting-patches.rst: avoid using ReST :doc:`foo` markup

[Rob Herring]

On Wed, Jun 16, 2021 at 12:27 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>
> ---
>  .../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.

These don't match $subject.

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

Is this new? You did review my oneliner adding ':doc:' not too long ago.

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

Re: [PATCH v2 11/29] docs: devicetree: bindings: submitting-patches.rst: avoid using ReST :doc:`foo` markup

[Mauro Carvalho Chehab]

Em Wed, 16 Jun 2021 16:08:05 -0600
Rob Herring <robh+dt@kernel.org> escreveu:

> On Wed, Jun 16, 2021 at 12:27 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>
> > ---
> >  .../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.  
> 
> These don't match $subject.

Well, I just seek for all places where Documentation/* are, and adjusted
them to 80-columns. I'll add a comment. 

> 
> >
> >    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.  
> 
> Is this new? You did review my oneliner adding ':doc:' not too long ago.

Yes. It is due to some discussion we had upstream:

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

While the html/latex/pdf output is identical (as automarkup.py will
convert Documentation/foo.rst into a cross-reference), using full path
names allow developers to jump directly to other documents when they
have the path name.

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



Thanks,
Mauro

Re: [PATCH v2 00/29] docs: avoid using ReST :doc:`foo` tag

[Jonathan Corbet]

Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:

> (Maintainers bcc, to avoid too many recipient troubles)
>
> As discussed at:
> 	https://lore.kernel.org/linux-doc/871r9k6rmy.fsf@meer.lwn.net/
>
> It is better to avoid using :doc:`foo` to refer to Documentation/foo.rst, as the
> automarkup.py extension should handle it automatically, on most cases.

I've applied the set, thanks.

jon