| lists.openwall.net | lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC | |
|
Open Source and information security mailing list archives
| ||
|
Message-Id: <cover.1622898327.git.mchehab+huawei@kernel.org>
Date: Sat, 5 Jun 2021 15:17:59 +0200
From: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To: "Jonathan Corbet" <corbet@....net>,
Linux Doc Mailing List <linux-doc@...r.kernel.org>
Cc: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>,
linux-kernel@...r.kernel.org, bpf@...r.kernel.org,
coresight@...ts.linaro.org, devicetree@...r.kernel.org,
kunit-dev@...glegroups.com, kvm@...r.kernel.org,
linux-acpi@...r.kernel.org, linux-arm-kernel@...ts.infradead.org,
linux-gpio@...r.kernel.org, linux-hwmon@...r.kernel.org,
linux-i2c@...r.kernel.org, linux-kselftest@...r.kernel.org,
linux-media@...r.kernel.org, linux-pci@...r.kernel.org,
linux-pm@...r.kernel.org, linux-security-module@...r.kernel.org,
netdev@...r.kernel.org
Subject: [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag
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
Powered by blists - more mailing lists