Received-SPF: pass (google.com: domain of linux-kernel+bounces-9086-linux.lists.archive=gmail.com@vger.kernel.org designates 147.75.199.223 as permitted sender) client-ip=147.75.199.223;
Precedence: bulk
MIME-Version: 1.0
References: <20231215235428.243211-1-ojeda@kernel.org>
In-Reply-To: <20231215235428.243211-1-ojeda@kernel.org>
From: Miguel Ojeda <miguel.ojeda.sandonis@gmail.com>
Date: Thu, 21 Dec 2023 22:38:49 +0100
Message-ID: <CANiq72kfpdNdCXtxFM-YVLuOp34u_edieX0q_a94-5kAxdGRWg@mail.gmail.com>
Subject: Re: [PATCH] rust: support `srctree`-relative links
To: Miguel Ojeda <ojeda@kernel.org>
Cc: Wedson Almeida Filho <wedsonaf@gmail.com>, Alex Gaynor <alex.gaynor@gmail.com>, 
	Boqun Feng <boqun.feng@gmail.com>, Gary Guo <gary@garyguo.net>, 
	=?UTF-8?Q?Bj=C3=B6rn_Roy_Baron?= <bjorn3_gh@protonmail.com>, 
	Benno Lossin <benno.lossin@proton.me>, Andreas Hindborg <a.hindborg@samsung.com>, 
	Alice Ryhl <aliceryhl@google.com>, rust-for-linux@vger.kernel.org, 
	linux-kernel@vger.kernel.org, patches@lists.linux.dev, 
	FUJITA Tomonori <fujita.tomonori@gmail.com>
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

On Sat, Dec 16, 2023 at 12:54=E2=80=AFAM Miguel Ojeda <ojeda@kernel.org> wr=
ote:
>
> Some of our links use relative paths in order to point to files in the
> source tree, e.g.:
>
>     //! C header: [`include/linux/printk.h`](../../../../include/linux/pr=
intk.h)
>     /// [`struct mutex`]: ../../../../include/linux/mutex.h
>
> These are problematic because they are hard to maintain and do not suppor=
t
> `O=3D` builds.
>
> Instead, provide support for `srctree`-relative links, e.g.:
>
>     //! C header: [`include/linux/printk.h`](srctree/include/linux/printk=
.h)
>     /// [`struct mutex`]: srctree/include/linux/mutex.h
>
> The links are fixed after `rustdoc` generation to be based on the absolut=
e
> path to the source tree.
>
> Essentially, this is the automatic version of Tomonori's fix [1],
> suggested by Gary [2].
>
> Suggested-by: Gary Guo <gary@garyguo.net>
> Reported-by: FUJITA Tomonori <fujita.tomonori@gmail.com>
> Closes: https://lore.kernel.org/r/20231026.204058.2167744626131849993.fuj=
ita.tomonori@gmail.com [1]
> Fixes: 48fadf440075 ("docs: Move rustdoc output, cross-reference it")
> Link: https://lore.kernel.org/rust-for-linux/20231026154525.6d14b495@euge=
o/ [2]
> Signed-off-by: Miguel Ojeda <ojeda@kernel.org>

Applied to `rust-next` -- thanks everyone!

By the way, since I didn't mention it: this obviously requires the
source tree to be available at its path, so we may want to improve on
that later (e.g. exporting the needed files in the output folder), but
it is a strict improvement since it fixes the immediate issue, it
cleans the paths already reducing the maintenance burden (i.e. we can
keep the syntax even if we change the rest) and is a smaller change if
we decide to send it to stable later.

Cheers,
Miguel