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

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

[Mauro Carvalho Chehab]

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

[PATCH 26/34] docs: PCI: endpoint: pci-endpoint-cfs.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>
---
 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

Re: [PATCH 26/34] docs: PCI: endpoint: pci-endpoint-cfs.rst: avoid using ReSt :doc:`foo` markup

[Bjorn Helgaas]

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
> 

Re: [PATCH 26/34] docs: PCI: endpoint: pci-endpoint-cfs.rst: avoid using ReSt :doc:`foo` markup

[Mauro Carvalho Chehab]

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

[PATCH 27/34] docs: PCI: pci.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>
---
 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

Re: [PATCH 27/34] docs: PCI: pci.rst: avoid using ReSt :doc:`foo` markup

[Bjorn Helgaas]

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
> 

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

[Mauro Carvalho Chehab]

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

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

[Nícolas F. R. A. Prado]

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

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

[Mauro Carvalho Chehab]

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

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

[Nícolas F. R. A. Prado]

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

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

[Mauro Carvalho Chehab]

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

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

[Nícolas F. R. A. Prado]

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

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

[Mauro Carvalho Chehab]

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