Re: [PATCH] docs: Remove literal markup from Documentation/ paths

[Jonathan Cameron]

On Fri, 04 Apr 2025 11:37:28 -0400
Nícolas F. R. A. Prado <nfraprado@xxxxxxxxxxxxx> wrote:

> Given that the automarkup Sphinx plugin cross-references
> "Documentation/*.rst" strings in the text to the corresponding
> documents, surrounding those strings with the literal markup (``) not
> only adds unnecessary markup in the source files, but actually prevents
> the automatic cross-referencing to happen (as it doesn't happen in
> literal blocks).
> 
> Remove all the occurrences of the literal markup in
> "Documentation/*.rst" paths, except when the actual source file is being
> referred. Also change the surrounding text when needed so it reads well
> both in the source and the web page (eg. 'see file Doc...' -> 'see
> Doc...').
> 
> Signed-off-by: Nícolas F. R. A. Prado <nfraprado@xxxxxxxxxxxxx>
> ---
>  Documentation/admin-guide/mm/numa_memory_policy.rst       | 2 +-
>  Documentation/admin-guide/serial-console.rst              | 2 +-
>  Documentation/driver-api/dmaengine/client.rst             | 2 +-
>  Documentation/driver-api/nvdimm/security.rst              | 2 +-
>  Documentation/filesystems/fscrypt.rst                     | 4 ++--
>  Documentation/iio/adis16475.rst                           | 4 ++--
>  Documentation/iio/adis16480.rst                           | 4 ++--
>  Documentation/iio/adis16550.rst                           | 4 ++--
>  Documentation/iio/adxl380.rst                             | 4 ++--

Split patch up by subsystem would be a good thing here as we may
get other changes to these docs during the cycle and resulting
merge conflicts if this all goes in as one patch.


>  Documentation/kernel-hacking/hacking.rst                  | 6 +++---
>  Documentation/kernel-hacking/locking.rst                  | 2 +-
>  Documentation/networking/dsa/b53.rst                      | 2 +-
>  Documentation/networking/dsa/bcm_sf2.rst                  | 2 +-
>  Documentation/networking/dsa/dsa.rst                      | 2 +-
>  Documentation/networking/dsa/lan9303.rst                  | 2 +-
>  Documentation/networking/phy-link-topology.rst            | 2 +-
>  Documentation/process/adding-syscalls.rst                 | 2 +-
>  Documentation/process/submit-checklist.rst                | 7 ++++---
>  Documentation/security/keys/trusted-encrypted.rst         | 4 ++--
>  Documentation/sound/kernel-api/writing-an-alsa-driver.rst | 2 +-
>  Documentation/userspace-api/media/v4l/dev-sliced-vbi.rst  | 2 +-
>  Documentation/userspace-api/media/v4l/diff-v4l.rst        | 2 +-
>  Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst | 4 ++--
>  Documentation/virt/uml/user_mode_linux_howto_v2.rst       | 2 +-
>  24 files changed, 36 insertions(+), 35 deletions(-)