From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <linux-hwmon-owner@kernel.org>
X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on
	aws-us-west-2-korg-lkml-1.web.codeaurora.org
X-Spam-Level: 
X-Spam-Status: No, score=-10.8 required=3.0 tests=BAYES_00,DKIM_SIGNED,
	DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_PATCH,
	MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS autolearn=unavailable
	autolearn_force=no version=3.4.0
Received: from mail.kernel.org (mail.kernel.org [198.145.29.99])
	by smtp.lore.kernel.org (Postfix) with ESMTP id A00FCC4743E
	for <linux-hwmon@archiver.kernel.org>; Sat,  5 Jun 2021 15:12:06 +0000 (UTC)
Received: from vger.kernel.org (vger.kernel.org [23.128.96.18])
	by mail.kernel.org (Postfix) with ESMTP id 7FB25613F3
	for <linux-hwmon@archiver.kernel.org>; Sat,  5 Jun 2021 15:12:06 +0000 (UTC)
Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand
        id S229981AbhFEPNw (ORCPT <rfc822;linux-hwmon@archiver.kernel.org>);
        Sat, 5 Jun 2021 11:13:52 -0400
Received: from relay7-d.mail.gandi.net ([217.70.183.200]:37381 "EHLO
        relay7-d.mail.gandi.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org
        with ESMTP id S229930AbhFEPNv (ORCPT
        <rfc822;linux-hwmon@vger.kernel.org>); Sat, 5 Jun 2021 11:13:51 -0400
Received: (Authenticated sender: n@nfraprado.net)
        by relay7-d.mail.gandi.net (Postfix) with ESMTPSA id 8D0E020002;
        Sat,  5 Jun 2021 15:11:51 +0000 (UTC)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=nfraprado.net;
        s=gm1; t=1622905920;
        h=from:from:reply-to:subject:subject:date:date:message-id:message-id:
         to:to:cc:cc:mime-version:mime-version:content-type:content-type:
         content-transfer-encoding:content-transfer-encoding:
         in-reply-to:in-reply-to:references:references;
        bh=Vv4/s0oEatJqm6xOhfhv4SCtKvstG4qCMEYIIpldPy0=;
        b=c3g7o4uEF0JTLo7vMH1ksgmeTVLRz9pP7cqUyB/h+W5DpIymRZemkGu49jcerS4uE/XJQf
        trJLU85vbJBVfZWGFuOsMTCnYVhfSXPxbndF40vAAuKJ0CB9s0KsBjrJ/9zkVZxSK1kZX7
        WPbrr1BsDbMi3udCw9RD6VTWhB3rbd/s8FPEH1mqg/QoOWJo+2T2Gjzqe5dJfYUoJ5uWJi
        mYxE058i/H4Cq0cW3G8Q81eikJU5bVOUF0NbPJeQ/P3UbZMAhOkhJpLRUvntlO2RvnJ5ez
        x1AXAnbGKQtYTh67G2z/msrTC09lBJ7xVdF4ukLxuwInJgcg+Ro9QEyCJg7rbQ==
Date:   Sat, 5 Jun 2021 12:11:09 -0300
From:   =?utf-8?B?TsOtY29sYXMgRi4gUi4gQS4=?= Prado <n@nfraprado.net>
To:     Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Cc:     Jonathan Corbet <corbet@lwn.net>,
        Linux Doc Mailing List <linux-doc@vger.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: Re: [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag
Message-ID: <20210605151109.axm3wzbcstsyxczp@notapiano>
References: <cover.1622898327.git.mchehab+huawei@kernel.org>
MIME-Version: 1.0
Content-Type: text/plain; charset=iso-8859-1
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
In-Reply-To: <cover.1622898327.git.mchehab+huawei@kernel.org>
Precedence: bulk
List-ID: <linux-hwmon.vger.kernel.org>
X-Mailing-List: linux-hwmon@vger.kernel.org

Hi Mauro,

On Sat, Jun 05, 2021 at 03:17:59PM +0200, Mauro Carvalho Chehab wrote:
> 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.

What I think is happening here is that we're using rST's syntax for definition
lists [1]. automarkup.py ignores literal nodes, and perhaps a definition is
considered a literal by Sphinx. Adding a blank line after the Documentation/...
or removing the additional indentation makes it work, like you did in your
2nd and 3rd patch, since then it's not a definition anymore, although then the
visual output is different as well.

I'm not sure this is something we need to fix. Does it make sense to use
definition lists for links like that? If it does, I guess one option would be to
whitelist definition lists so they aren't ignored by automarkup, but I feel
this could get ugly really quickly.

FWIW note that it's also possible to use relative paths to docs with automarkup.

Thanks,
Nícolas

[1] https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#definition-lists

> 
> 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
> 
> 

From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <SRS0=NGUK=K7=lists.infradead.org=linux-arm-kernel-bounces+linux-arm-kernel=archiver.kernel.org@kernel.org>
X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on
	aws-us-west-2-korg-lkml-1.web.codeaurora.org
X-Spam-Level: 
X-Spam-Status: No, score=-9.1 required=3.0 tests=BAYES_00,DKIMWL_WL_HIGH,
	DKIM_SIGNED,DKIM_VALID,HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_PATCH,
	MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS autolearn=ham autolearn_force=no
	version=3.4.0
Received: from mail.kernel.org (mail.kernel.org [198.145.29.99])
	by smtp.lore.kernel.org (Postfix) with ESMTP id 263A3C47082
	for <linux-arm-kernel@archiver.kernel.org>; Sat,  5 Jun 2021 15:13:59 +0000 (UTC)
Received: from bombadil.infradead.org (bombadil.infradead.org [198.137.202.133])
	(using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits))
	(No client certificate requested)
	by mail.kernel.org (Postfix) with ESMTPS id E5510613B4
	for <linux-arm-kernel@archiver.kernel.org>; Sat,  5 Jun 2021 15:13:58 +0000 (UTC)
DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org E5510613B4
Authentication-Results: mail.kernel.org; dmarc=none (p=none dis=none) header.from=nfraprado.net
Authentication-Results: mail.kernel.org; spf=none smtp.mailfrom=linux-arm-kernel-bounces+linux-arm-kernel=archiver.kernel.org@lists.infradead.org
DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed;
	d=lists.infradead.org; s=bombadil.20210309; h=Sender:
	Content-Transfer-Encoding:Content-Type:List-Subscribe:List-Help:List-Post:
	List-Archive:List-Unsubscribe:List-Id:In-Reply-To:MIME-Version:References:
	Message-ID:Subject:Cc:To:From:Date:Reply-To:Content-ID:Content-Description:
	Resent-Date:Resent-From:Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:
	List-Owner; bh=Xos/Mjt7h1cWNOiIDO208Ntq5NJRtb+2tKrzwy2YfRA=; b=PZapK8XQWdZGh7
	SMHnlxdPu8fXj+5qaixQIJidBAa46kwXeRCIUKRSm72jzyi1z1bLw/YDD/hM2jt4gGFwEEqooz9DO
	Qp9TCTAMsNvDqV6u9IbKXo9oFWb6NiscKuLjssFc9kAqLnFdMN51q0hidK9oWk7AMW6GWfRNJJg7C
	OweTZA77HzZZaJq+J98tdOemonen455WFmHX3pK/r2EGss5B7lC0qlP/RmgGIEsqPR706XO5G3GT5
	yTSW9oqv7xU2jXd6SMKNIIsfGLok/4M0wIDGgXNRebFzgltTe9K4vDMOCOe7TrCZdcj25O8HU0Duq
	culdIzZZe2xgXPeo/TZw==;
Received: from localhost ([::1] helo=bombadil.infradead.org)
	by bombadil.infradead.org with esmtp (Exim 4.94.2 #2 (Red Hat Linux))
	id 1lpXy6-00GjOt-VL; Sat, 05 Jun 2021 15:12:11 +0000
Received: from relay7-d.mail.gandi.net ([217.70.183.200])
 by bombadil.infradead.org with esmtps (Exim 4.94.2 #2 (Red Hat Linux))
 id 1lpXy2-00GjNO-47
 for linux-arm-kernel@lists.infradead.org; Sat, 05 Jun 2021 15:12:08 +0000
Received: (Authenticated sender: n@nfraprado.net)
 by relay7-d.mail.gandi.net (Postfix) with ESMTPSA id 8D0E020002;
 Sat,  5 Jun 2021 15:11:51 +0000 (UTC)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=nfraprado.net;
 s=gm1; t=1622905920;
 h=from:from:reply-to:subject:subject:date:date:message-id:message-id:
 to:to:cc:cc:mime-version:mime-version:content-type:content-type:
 content-transfer-encoding:content-transfer-encoding:
 in-reply-to:in-reply-to:references:references;
 bh=Vv4/s0oEatJqm6xOhfhv4SCtKvstG4qCMEYIIpldPy0=;
 b=c3g7o4uEF0JTLo7vMH1ksgmeTVLRz9pP7cqUyB/h+W5DpIymRZemkGu49jcerS4uE/XJQf
 trJLU85vbJBVfZWGFuOsMTCnYVhfSXPxbndF40vAAuKJ0CB9s0KsBjrJ/9zkVZxSK1kZX7
 WPbrr1BsDbMi3udCw9RD6VTWhB3rbd/s8FPEH1mqg/QoOWJo+2T2Gjzqe5dJfYUoJ5uWJi
 mYxE058i/H4Cq0cW3G8Q81eikJU5bVOUF0NbPJeQ/P3UbZMAhOkhJpLRUvntlO2RvnJ5ez
 x1AXAnbGKQtYTh67G2z/msrTC09lBJ7xVdF4ukLxuwInJgcg+Ro9QEyCJg7rbQ==
Date: Sat, 5 Jun 2021 12:11:09 -0300
From: =?utf-8?B?TsOtY29sYXMgRi4gUi4gQS4=?= Prado <n@nfraprado.net>
To: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Cc: Jonathan Corbet <corbet@lwn.net>,
 Linux Doc Mailing List <linux-doc@vger.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: Re: [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag
Message-ID: <20210605151109.axm3wzbcstsyxczp@notapiano>
References: <cover.1622898327.git.mchehab+huawei@kernel.org>
MIME-Version: 1.0
Content-Disposition: inline
In-Reply-To: <cover.1622898327.git.mchehab+huawei@kernel.org>
X-CRM114-Version: 20100106-BlameMichelson ( TRE 0.8.0 (BSD) ) MR-646709E3 
X-CRM114-CacheID: sfid-20210605_081206_491668_C59C631F 
X-CRM114-Status: GOOD (  32.38  )
X-BeenThere: linux-arm-kernel@lists.infradead.org
X-Mailman-Version: 2.1.34
Precedence: list
List-Id: <linux-arm-kernel.lists.infradead.org>
List-Unsubscribe: <http://lists.infradead.org/mailman/options/linux-arm-kernel>, 
 <mailto:linux-arm-kernel-request@lists.infradead.org?subject=unsubscribe>
List-Archive: <http://lists.infradead.org/pipermail/linux-arm-kernel/>
List-Post: <mailto:linux-arm-kernel@lists.infradead.org>
List-Help: <mailto:linux-arm-kernel-request@lists.infradead.org?subject=help>
List-Subscribe: <http://lists.infradead.org/mailman/listinfo/linux-arm-kernel>, 
 <mailto:linux-arm-kernel-request@lists.infradead.org?subject=subscribe>
Content-Type: text/plain; charset="iso-8859-1"
Content-Transfer-Encoding: quoted-printable
Sender: "linux-arm-kernel" <linux-arm-kernel-bounces@lists.infradead.org>
Errors-To: linux-arm-kernel-bounces+linux-arm-kernel=archiver.kernel.org@lists.infradead.org

Hi Mauro,

On Sat, Jun 05, 2021 at 03:17:59PM +0200, Mauro Carvalho Chehab wrote:
> 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.

What I think is happening here is that we're using rST's syntax for definit=
ion
lists [1]. automarkup.py ignores literal nodes, and perhaps a definition is
considered a literal by Sphinx. Adding a blank line after the Documentation=
/...
or removing the additional indentation makes it work, like you did in your
2nd and 3rd patch, since then it's not a definition anymore, although then =
the
visual output is different as well.

I'm not sure this is something we need to fix. Does it make sense to use
definition lists for links like that? If it does, I guess one option would =
be to
whitelist definition lists so they aren't ignored by automarkup, but I feel
this could get ugly really quickly.

FWIW note that it's also possible to use relative paths to docs with automa=
rkup.

Thanks,
N=EDcolas

[1] https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#defi=
nition-lists

> =

> 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=3D<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
> =

> =


_______________________________________________
linux-arm-kernel mailing list
linux-arm-kernel@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel