Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18;
Date:   Thu, 3 Jun 2021 13:35:14 +0200
From:   Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
To:     Jonathan Corbet <corbet@lwn.net>
Cc:     Peter Zijlstra <peterz@infradead.org>,
        Linux Doc Mailing List <linux-doc@vger.kernel.org>,
        "Guilherme G. Piccoli" <gpiccoli@canonical.com>,
        Andrew Morton <akpm@linux-foundation.org>,
        Daniel Borkmann <daniel@iogearbox.net>,
        Kees Cook <keescook@chromium.org>,
        Lepton Wu <ytht.net@gmail.com>, Mel Gorman <mgorman@suse.de>,
        Qais Yousef <qais.yousef@arm.com>,
        Randy Dunlap <rdunlap@infradead.org>,
        Rasmus Villemoes <linux@rasmusvillemoes.dk>,
        Stephen Kitt <steve@sk2.org>, Wang Qing <wangqing@vivo.com>,
        linux-kernel@vger.kernel.org
Subject: Re: [PATCH 07/12] docs: accounting: update delay-accounting.rst
 reference
Message-ID: <20210603133514.3688071f@coco.lan>
In-Reply-To: <871r9k6rmy.fsf@meer.lwn.net>
References: <cover.1622648507.git.mchehab+huawei@kernel.org>
        <629b0bd21d02c8faef9a6d17d9eee8ff612715e0.1622648507.git.mchehab+huawei@kernel.org>
        <YLe0BQcrnfRgH1dV@hirez.programming.kicks-ass.net>
        <20210602200121.64a828a1@coco.lan>
        <871r9k6rmy.fsf@meer.lwn.net>
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit
Precedence: bulk

Em Wed, 02 Jun 2021 12:36:05 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
> 
> > That's said, automarkup.py has a rule to convert Documentation/<foo>.rst
> > into :doc:`<foo>`. So, an alternative approach would be to convert
> > treewide all :doc:`<foo>` into Documentation/<foo>.rst and add something 
> > at checkpatch.pl to recommend to avoid :doc: notation.  
> 
> That seems like the right approach to me.  We have the automarkup
> capability, we might as well make use of it...

Hmm...

This patch caused a regression:

<patch>
PATCH] media: admin-guide: avoid using ReSt :doc:`foo` markup

The :doc:`foo` tag is auto-generated via automarkup.py.
So, use the filename at the sources, instead of :doc:`foo`.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

diff --git a/Documentation/admin-guide/media/index.rst b/Documentation/admin-guide/media/index.rst
index 6e0d2bae7154..5dbf6d02096a 100644
--- a/Documentation/admin-guide/media/index.rst
+++ b/Documentation/admin-guide/media/index.rst
@@ -11,10 +11,10 @@ its supported drivers.
 
 Please see:
 
-- :doc:`/userspace-api/media/index`
+- Documentation/userspace-api/media/index.rst
      for the userspace APIs used on media devices.
 
-- :doc:`/driver-api/media/index`
+- Documentation/driver-api/media/index.rst
      for driver development information and Kernel APIs used by
      media devices;
</patch>

This is the diff for the HTML output:

<diff>
diff --git a/admin-guide/media/index.html b/admin-guide/media/index.html
index 94c0cdf51579..28c083b75896 100644
--- a/admin-guide/media/index.html
+++ b/admin-guide/media/index.html
@@ -339,12 +339,12 @@ its supported drivers.</p>
 <p>Please see:</p>
 <ul class="simple">
 <li><dl class="simple">
-<dt><a class="reference internal" href="../../userspace-api/media/index.html"><span class="doc">Linux Media Infrastructure userspace API</span></a></dt><dd><p>for the userspace APIs used on media devices.</p>
+<dt>Documentation/userspace-api/media/index.rst</dt><dd><p>for the userspace APIs used on media devices.</p>
 </dd>
 </dl>
 </li>
 <li><dl class="simple">
-<dt><a class="reference internal" href="../../driver-api/media/index.html"><span class="doc">Media subsystem kernel internal API</span></a></dt><dd><p>for driver development information and Kernel APIs used by
+<dt>Documentation/driver-api/media/index.rst</dt><dd><p>for driver development information and Kernel APIs used by
 media devices;</p>
 </dd>
 </dl>
</diff>

It sounds that automarkup.py ignored it. Maybe because it is inside
a list?

Thanks,
Mauro