From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
To: "Jonathan Corbet" <corbet@lwn.net>,
Linux Doc Mailing List <linux-doc@vger.kernel.org>
Cc: 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: Re: [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag
Date: Sat, 5 Jun 2021 15:37:01 +0200 [thread overview]
Message-ID: <20210605153701.56a8e2d8@coco.lan> (raw)
In-Reply-To: <cover.1622898327.git.mchehab+huawei@kernel.org>
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
next prev parent reply other threads:[~2021-06-05 13:37 UTC|newest]
Thread overview: 63+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-06-05 13:17 [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag Mauro Carvalho Chehab
2021-06-05 13:18 ` [PATCH 01/34] docs: devices.rst: better reference documentation docs Mauro Carvalho Chehab
2021-06-05 13:18 ` [PATCH 02/34] docs: dev-tools: kunit: don't use a table for docs name Mauro Carvalho Chehab
2021-06-05 15:43 ` David Gow
2021-06-05 16:06 ` Mauro Carvalho Chehab
2021-06-07 20:14 ` Brendan Higgins
2021-06-05 13:18 ` [PATCH 03/34] media: docs: */media/index.rst: don't use ReST doc:`foo` Mauro Carvalho Chehab
2021-06-05 13:18 ` [PATCH 04/34] media: userspace-api: avoid using ReST :doc:`foo` markup Mauro Carvalho Chehab
2021-06-05 13:18 ` [PATCH 05/34] media: driver-api: drivers: " Mauro Carvalho Chehab
2021-06-05 13:18 ` [PATCH 06/34] media: admin-guide: " Mauro Carvalho Chehab
2021-06-05 13:18 ` [PATCH 07/34] docs: admin-guide: pm: avoid using ReSt " Mauro Carvalho Chehab
2021-06-05 13:18 ` [PATCH 08/34] docs: admin-guide: hw-vuln: avoid using ReST " Mauro Carvalho Chehab
2021-06-05 13:18 ` [PATCH 09/34] docs: admin-guide: sysctl: " Mauro Carvalho Chehab
2021-06-05 13:18 ` [PATCH 10/34] docs: block: biodoc.rst: avoid using ReSt " Mauro Carvalho Chehab
2021-06-05 13:18 ` [PATCH 11/34] docs: bpf: bpf_lsm.rst: " Mauro Carvalho Chehab
2021-06-05 13:18 ` [PATCH 12/34] docs: core-api: " Mauro Carvalho Chehab
2021-06-05 13:18 ` [PATCH 13/34] docs: dev-tools: testing-overview.rst: " Mauro Carvalho Chehab
2021-06-05 15:43 ` David Gow
2021-06-05 16:13 ` Mauro Carvalho Chehab
2021-06-05 13:18 ` [PATCH 14/34] docs: dev-tools: kunit: avoid using ReST " Mauro Carvalho Chehab
2021-06-05 15:44 ` David Gow
2021-06-16 6:00 ` Mauro Carvalho Chehab
2021-06-16 6:13 ` Mauro Carvalho Chehab
2021-06-07 20:20 ` Brendan Higgins
2021-06-05 13:18 ` [PATCH 15/34] docs: devicetree: bindings: submitting-patches.rst: avoid using ReSt " Mauro Carvalho Chehab
2021-06-05 13:18 ` [PATCH 16/34] docs: doc-guide: " Mauro Carvalho Chehab
2021-06-05 13:18 ` [PATCH 17/34] docs: driver-api: " Mauro Carvalho Chehab
2021-06-05 13:18 ` [PATCH 18/34] docs: driver-api: gpio: using-gpio.rst: " Mauro Carvalho Chehab
2021-06-05 16:25 ` Linus Walleij
2021-06-05 13:18 ` [PATCH 19/34] docs: driver-api: surface_aggregator: " Mauro Carvalho Chehab
2021-06-05 14:14 ` Maximilian Luz
2021-06-07 9:31 ` Hans de Goede
2021-06-07 9:55 ` Mauro Carvalho Chehab
2021-06-07 10:07 ` Hans de Goede
2021-06-05 13:18 ` [PATCH 20/34] docs: driver-api: usb: " Mauro Carvalho Chehab
2021-06-05 13:18 ` [PATCH 21/34] docs: firmware-guide: acpi: " Mauro Carvalho Chehab
2021-06-05 13:18 ` [PATCH 22/34] docs: hwmon: adm1177.rst: " Mauro Carvalho Chehab
2021-06-06 13:01 ` Guenter Roeck
2021-06-05 13:18 ` [PATCH 23/34] docs: i2c: " Mauro Carvalho Chehab
2021-06-05 15:13 ` Wolfram Sang
2021-06-05 13:18 ` [PATCH 24/34] docs: kernel-hacking: hacking.rst: " Mauro Carvalho Chehab
2021-06-05 13:18 ` [PATCH 25/34] docs: networking: devlink: " Mauro Carvalho Chehab
2021-06-05 13:18 ` [PATCH 26/34] docs: PCI: endpoint: pci-endpoint-cfs.rst: " 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:18 ` [PATCH 28/34] docs: process: submitting-patches.rst: " Mauro Carvalho Chehab
2021-06-05 13:18 ` [PATCH 29/34] docs: security: landlock.rst: " Mauro Carvalho Chehab
2021-06-05 13:18 ` [PATCH 30/34] docs: trace: coresight: coresight.rst: " Mauro Carvalho Chehab
2021-06-08 15:23 ` Mathieu Poirier
2021-06-05 13:18 ` [PATCH 31/34] docs: trace: ftrace.rst: " Mauro Carvalho Chehab
2021-06-05 13:18 ` [PATCH 32/34] docs: userspace-api: landlock.rst: " Mauro Carvalho Chehab
2021-06-05 13:18 ` [PATCH 33/34] docs: virt: kvm: s390-pv-boot.rst: " Mauro Carvalho Chehab
2021-06-05 13:18 ` [PATCH 34/34] docs: x86: " Mauro Carvalho Chehab
2021-06-07 15:21 ` Peter Zijlstra
2021-06-05 13:37 ` Mauro Carvalho Chehab [this message]
2021-06-05 15:11 ` [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag 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=20210605153701.56a8e2d8@coco.lan \
--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).