Em Sat, 5 Jun 2021 15:17:59 +0200 Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx> escreveu: > As discussed at: > https://lore.kernel.org/linux-doc/871r9k6rmy.fsf@xxxxxxxxxxxx/ > > 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
