As discussed at:
https://lore.kernel.org/linux-doc/[email protected]/
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
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 <[email protected]>
---
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 [email protected]. 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: [email protected]
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: [email protected] on all stable
+process nor the requirement to Cc: [email protected] 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 [email protected] people!
<https://lore.kernel.org/r/[email protected]>
-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/[email protected]>
--
2.31.1
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 <[email protected]>
---
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
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 <[email protected]>
---
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
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 <[email protected]>
---
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
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 <[email protected]>
---
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
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 <[email protected]>
---
.../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
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 <[email protected]>
---
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
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 <[email protected]>
---
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
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 <[email protected]>
---
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 <[email protected]>
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
Em Sat, 5 Jun 2021 15:17:59 +0200
Mauro Carvalho Chehab <[email protected]> escreveu:
> As discussed at:
> https://lore.kernel.org/linux-doc/[email protected]/
>
> 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
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/[email protected]/
>
> 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
>
>
On Sat, Jun 5, 2021 at 9:18 PM Mauro Carvalho Chehab
<[email protected]> 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 <[email protected]>
> ---
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 <[email protected]>
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 [email protected].
> To view this discussion on the web visit https://groups.google.com/d/msgid/kunit-dev/08ac283ac5bdc2664255a7ad34514e50d3ed85d8.1622898327.git.mchehab%2Bhuawei%40kernel.org.
Em Sat, 5 Jun 2021 23:43:22 +0800
David Gow <[email protected]> escreveu:
> On Sat, Jun 5, 2021 at 9:18 PM Mauro Carvalho Chehab
> <[email protected]> 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 <[email protected]>
> > ---
>
> 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 <[email protected]>
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 [email protected].
> > 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
On Sat, Jun 5, 2021 at 3:18 PM Mauro Carvalho Chehab
<[email protected]> 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 <[email protected]>
Reviewed-by: Linus Walleij <[email protected]>
Yours,
Linus Walleij
Em Sat, 5 Jun 2021 12:11:09 -0300
Nícolas F. R. A. Prado <[email protected]> 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/[email protected]/
> >
> > 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
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 <[email protected]> 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/[email protected]/
> > >
> > > 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
Em Sun, 6 Jun 2021 19:52:25 -0300
Nícolas F. R. A. Prado <[email protected]> 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 <[email protected]> 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/[email protected]/
> > > >
> > > > 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
On Sat, Jun 5, 2021 at 6:18 AM Mauro Carvalho Chehab
<[email protected]> 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 <[email protected]>
Thanks!
Acked-by: Brendan Higgins <[email protected]>
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 <[email protected]> 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 <[email protected]> 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/[email protected]/
> > > > >
> > > > > 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
Em Mon, 7 Jun 2021 21:34:58 -0300
Nícolas F. R. A. Prado <[email protected]> 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 <[email protected]> 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 <[email protected]> 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/[email protected]/
> > > > > >
> > > > > > 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
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 <[email protected]>
> ---
> Documentation/trace/coresight/coresight.rst | 8 +++++---
> 1 file changed, 5 insertions(+), 3 deletions(-)
>
Reviewed-by: Mathieu Poirier <[email protected]>
> 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
>
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 <[email protected]>
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 <[email protected]>
> ---
> 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
>
Em Thu, 10 Jun 2021 18:46:22 -0500
Bjorn Helgaas <[email protected]> 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 <[email protected]>
>
> 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/[email protected]/
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 <[email protected]>
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