From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
To: "Jonathan Corbet" <corbet@lwn.net>,
Linux Doc Mailing List <linux-doc@vger.kernel.org>
Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>,
linux-kernel@vger.kernel.org, bpf@vger.kernel.org,
coresight@lists.linaro.org, devicetree@vger.kernel.org,
kunit-dev@googlegroups.com, kvm@vger.kernel.org,
linux-acpi@vger.kernel.org, linux-arm-kernel@lists.infradead.org,
linux-gpio@vger.kernel.org, linux-hwmon@vger.kernel.org,
linux-i2c@vger.kernel.org, linux-kselftest@vger.kernel.org,
linux-media@vger.kernel.org, linux-pci@vger.kernel.org,
linux-pm@vger.kernel.org, linux-security-module@vger.kernel.org,
netdev@vger.kernel.org
Subject: [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag
Date: Sat, 5 Jun 2021 15:17:59 +0200 [thread overview]
Message-ID: <cover.1622898327.git.mchehab+huawei@kernel.org> (raw)
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
next reply other threads:[~2021-06-05 13:18 UTC|newest]
Thread overview: 13+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-06-05 13:17 Mauro Carvalho Chehab [this message]
2021-06-05 13:18 ` [PATCH 26/34] docs: PCI: endpoint: pci-endpoint-cfs.rst: avoid using ReSt :doc:`foo` markup Mauro Carvalho Chehab
2021-06-10 23:46 ` Bjorn Helgaas
2021-06-11 8:45 ` Mauro Carvalho Chehab
2021-06-05 13:18 ` [PATCH 27/34] docs: PCI: pci.rst: " Mauro Carvalho Chehab
2021-06-10 23:46 ` Bjorn Helgaas
2021-06-05 13:37 ` [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag Mauro Carvalho Chehab
2021-06-05 15:11 ` Nícolas F. R. A. Prado
2021-06-05 19:08 ` Mauro Carvalho Chehab
2021-06-06 22:52 ` Nícolas F. R. A. Prado
2021-06-07 7:34 ` Mauro Carvalho Chehab
2021-06-08 0:34 ` Nícolas F. R. A. Prado
2021-06-08 7:28 ` Mauro Carvalho Chehab
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=cover.1622898327.git.mchehab+huawei@kernel.org \
--to=mchehab+huawei@kernel.org \
--cc=bpf@vger.kernel.org \
--cc=corbet@lwn.net \
--cc=coresight@lists.linaro.org \
--cc=devicetree@vger.kernel.org \
--cc=kunit-dev@googlegroups.com \
--cc=kvm@vger.kernel.org \
--cc=linux-acpi@vger.kernel.org \
--cc=linux-arm-kernel@lists.infradead.org \
--cc=linux-doc@vger.kernel.org \
--cc=linux-gpio@vger.kernel.org \
--cc=linux-hwmon@vger.kernel.org \
--cc=linux-i2c@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-kselftest@vger.kernel.org \
--cc=linux-media@vger.kernel.org \
--cc=linux-pci@vger.kernel.org \
--cc=linux-pm@vger.kernel.org \
--cc=linux-security-module@vger.kernel.org \
--cc=netdev@vger.kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).