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/printk.h)
/// [`struct mutex`]: ../../../../include/linux/mutex.h
These are problematic because they are hard to maintain and do not support
`O=` 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 absolute
path to the source tree.
Essentially, this is the automatic version of Tomonori's fix [1],
suggested by Gary [2].
Suggested-by: Gary Guo <[email protected]>
Reported-by: FUJITA Tomonori <[email protected]>
Closes: https://lore.kernel.org/r/[email protected] [1]
Fixes: 48fadf440075 ("docs: Move rustdoc output, cross-reference it")
Link: https://lore.kernel.org/rust-for-linux/20231026154525.6d14b495@eugeo/ [2]
Signed-off-by: Miguel Ojeda <[email protected]>
---
Documentation/rust/coding-guidelines.rst | 13 +++++++++++++
rust/Makefile | 3 ++-
rust/kernel/error.rs | 2 +-
rust/kernel/ioctl.rs | 2 +-
rust/kernel/kunit.rs | 2 +-
rust/kernel/print.rs | 8 ++++----
rust/kernel/sync/condvar.rs | 2 +-
rust/kernel/sync/lock/mutex.rs | 2 +-
rust/kernel/sync/lock/spinlock.rs | 2 +-
rust/kernel/task.rs | 2 +-
rust/kernel/workqueue.rs | 2 +-
rust/macros/lib.rs | 2 +-
12 files changed, 28 insertions(+), 14 deletions(-)
diff --git a/Documentation/rust/coding-guidelines.rst b/Documentation/rust/coding-guidelines.rst
index aa8ed082613e..05542840b16c 100644
--- a/Documentation/rust/coding-guidelines.rst
+++ b/Documentation/rust/coding-guidelines.rst
@@ -177,6 +177,19 @@ please take a look at the ``rustdoc`` book at:
https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html
+In addition, the kernel supports creating links relative to the source tree by
+prefixing the link destination with ``srctree/``. For instance:
+
+.. code-block:: rust
+
+ //! C header: [`include/linux/printk.h`](srctree/include/linux/printk.h)
+
+or:
+
+.. code-block:: rust
+
+ /// [`struct mutex`]: srctree/include/linux/mutex.h
+
Naming
------
diff --git a/rust/Makefile b/rust/Makefile
index 543b37f6c77f..73ea24117f07 100644
--- a/rust/Makefile
+++ b/rust/Makefile
@@ -98,7 +98,8 @@ rustdoc: rustdoc-core rustdoc-macros rustdoc-compiler_builtins \
$(Q)find $(rustdoc_output) -name '*.html' -type f -print0 | xargs -0 sed -Ei \
-e 's:rust-logo-[0-9a-f]+\.svg:logo.svg:g' \
-e 's:favicon-[0-9a-f]+\.svg:logo.svg:g' \
- -e 's:<link rel="alternate icon" type="image/png" href="[/.]+/static\.files/favicon-(16x16|32x32)-[0-9a-f]+\.png">::g'
+ -e 's:<link rel="alternate icon" type="image/png" href="[/.]+/static\.files/favicon-(16x16|32x32)-[0-9a-f]+\.png">::g' \
+ -e 's:<a href="srctree/([^"]+)">:<a href="$(abs_srctree)/\1">:g'
$(Q)for f in $(rustdoc_output)/static.files/rustdoc-*.css; do \
echo ".logo-container > img { object-fit: contain; }" >> $$f; done
diff --git a/rust/kernel/error.rs b/rust/kernel/error.rs
index 032b64543953..abd06afb2d76 100644
--- a/rust/kernel/error.rs
+++ b/rust/kernel/error.rs
@@ -2,7 +2,7 @@
//! Kernel errors.
//!
-//! C header: [`include/uapi/asm-generic/errno-base.h`](../../../include/uapi/asm-generic/errno-base.h)
+//! C header: [`include/uapi/asm-generic/errno-base.h`](srctree/include/uapi/asm-generic/errno-base.h)
use crate::str::CStr;
diff --git a/rust/kernel/ioctl.rs b/rust/kernel/ioctl.rs
index c49e1a8d3fd0..f1d42ab69972 100644
--- a/rust/kernel/ioctl.rs
+++ b/rust/kernel/ioctl.rs
@@ -2,7 +2,7 @@
//! ioctl() number definitions
//!
-//! C header: [`include/asm-generic/ioctl.h`](../../../../include/asm-generic/ioctl.h)
+//! C header: [`include/asm-generic/ioctl.h`](srctree/include/asm-generic/ioctl.h)
#![allow(non_snake_case)]
diff --git a/rust/kernel/kunit.rs b/rust/kernel/kunit.rs
index 722655b2d62d..0ba77276ae7e 100644
--- a/rust/kernel/kunit.rs
+++ b/rust/kernel/kunit.rs
@@ -2,7 +2,7 @@
//! KUnit-based macros for Rust unit tests.
//!
-//! C header: [`include/kunit/test.h`](../../../../../include/kunit/test.h)
+//! C header: [`include/kunit/test.h`](srctree/include/kunit/test.h)
//!
//! Reference: <https://docs.kernel.org/dev-tools/kunit/index.html>
diff --git a/rust/kernel/print.rs b/rust/kernel/print.rs
index f48926e3e9fe..9b13aca832c2 100644
--- a/rust/kernel/print.rs
+++ b/rust/kernel/print.rs
@@ -2,7 +2,7 @@
//! Printing facilities.
//!
-//! C header: [`include/linux/printk.h`](../../../../include/linux/printk.h)
+//! C header: [`include/linux/printk.h`](srctree/include/linux/printk.h)
//!
//! Reference: <https://www.kernel.org/doc/html/latest/core-api/printk-basics.html>
@@ -48,7 +48,7 @@ pub mod format_strings {
/// The format string is always the same for a given level, i.e. for a
/// given `prefix`, which are the kernel's `KERN_*` constants.
///
- /// [`_printk`]: ../../../../include/linux/printk.h
+ /// [`_printk`]: srctree/include/linux/printk.h
const fn generate(is_cont: bool, prefix: &[u8; 3]) -> [u8; LENGTH] {
// Ensure the `KERN_*` macros are what we expect.
assert!(prefix[0] == b'\x01');
@@ -97,7 +97,7 @@ pub mod format_strings {
/// The format string must be one of the ones in [`format_strings`], and
/// the module name must be null-terminated.
///
-/// [`_printk`]: ../../../../include/linux/_printk.h
+/// [`_printk`]: srctree/include/linux/_printk.h
#[doc(hidden)]
#[cfg_attr(not(CONFIG_PRINTK), allow(unused_variables))]
pub unsafe fn call_printk(
@@ -120,7 +120,7 @@ pub unsafe fn call_printk(
///
/// Public but hidden since it should only be used from public macros.
///
-/// [`_printk`]: ../../../../include/linux/printk.h
+/// [`_printk`]: srctree/include/linux/printk.h
#[doc(hidden)]
#[cfg_attr(not(CONFIG_PRINTK), allow(unused_variables))]
pub fn call_printk_cont(args: fmt::Arguments<'_>) {
diff --git a/rust/kernel/sync/condvar.rs b/rust/kernel/sync/condvar.rs
index b679b6f6dbeb..f568802d4f8a 100644
--- a/rust/kernel/sync/condvar.rs
+++ b/rust/kernel/sync/condvar.rs
@@ -69,7 +69,7 @@ macro_rules! new_condvar {
/// }
/// ```
///
-/// [`struct wait_queue_head`]: ../../../include/linux/wait.h
+/// [`struct wait_queue_head`]: srctree/include/linux/wait.h
#[pin_data]
pub struct CondVar {
#[pin]
diff --git a/rust/kernel/sync/lock/mutex.rs b/rust/kernel/sync/lock/mutex.rs
index 09276fedc091..8c524a3ec45a 100644
--- a/rust/kernel/sync/lock/mutex.rs
+++ b/rust/kernel/sync/lock/mutex.rs
@@ -84,7 +84,7 @@ macro_rules! new_mutex {
/// }
/// ```
///
-/// [`struct mutex`]: ../../../../include/linux/mutex.h
+/// [`struct mutex`]: srctree/include/linux/mutex.h
pub type Mutex<T> = super::Lock<T, MutexBackend>;
/// A kernel `struct mutex` lock backend.
diff --git a/rust/kernel/sync/lock/spinlock.rs b/rust/kernel/sync/lock/spinlock.rs
index 91eb2c9e9123..068535ce1b29 100644
--- a/rust/kernel/sync/lock/spinlock.rs
+++ b/rust/kernel/sync/lock/spinlock.rs
@@ -82,7 +82,7 @@ macro_rules! new_spinlock {
/// }
/// ```
///
-/// [`spinlock_t`]: ../../../../include/linux/spinlock.h
+/// [`spinlock_t`]: srctree/include/linux/spinlock.h
pub type SpinLock<T> = super::Lock<T, SpinLockBackend>;
/// A kernel `spinlock_t` lock backend.
diff --git a/rust/kernel/task.rs b/rust/kernel/task.rs
index b2299bc7ac1f..9451932d5d86 100644
--- a/rust/kernel/task.rs
+++ b/rust/kernel/task.rs
@@ -2,7 +2,7 @@
//! Tasks (threads and processes).
//!
-//! C header: [`include/linux/sched.h`](../../../../include/linux/sched.h).
+//! C header: [`include/linux/sched.h`](srctree/include/linux/sched.h).
use crate::{bindings, types::Opaque};
use core::{marker::PhantomData, ops::Deref, ptr};
diff --git a/rust/kernel/workqueue.rs b/rust/kernel/workqueue.rs
index b67fb1ba168e..498397877376 100644
--- a/rust/kernel/workqueue.rs
+++ b/rust/kernel/workqueue.rs
@@ -132,7 +132,7 @@
//! }
//! ```
//!
-//! C header: [`include/linux/workqueue.h`](../../../../include/linux/workqueue.h)
+//! C header: [`include/linux/workqueue.h`](srctree/include/linux/workqueue.h)
use crate::{bindings, prelude::*, sync::Arc, sync::LockClassKey, types::Opaque};
use alloc::alloc::AllocError;
diff --git a/rust/macros/lib.rs b/rust/macros/lib.rs
index c42105c2ff96..3e3cb7449e58 100644
--- a/rust/macros/lib.rs
+++ b/rust/macros/lib.rs
@@ -20,7 +20,7 @@
/// The `type` argument should be a type which implements the [`Module`]
/// trait. Also accepts various forms of kernel metadata.
///
-/// C header: [`include/linux/moduleparam.h`](../../../include/linux/moduleparam.h)
+/// C header: [`include/linux/moduleparam.h`](srctree/include/linux/moduleparam.h)
///
/// [`Module`]: ../kernel/trait.Module.html
///
base-commit: a39b6ac3781d46ba18193c9dbb2110f31e9bffe9
--
2.43.0
On Sat, Dec 16, 2023 at 12:54 AM Miguel Ojeda <[email protected]> wrote:
>
> Instead, provide support for `srctree`-relative links, e.g.:
If we decide to go this way, then I plan to send this to stable later on.
Cheers,
Miguel
On 12/15/23 20:54, Miguel Ojeda wrote:
> 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/printk.h)
> /// [`struct mutex`]: ../../../../include/linux/mutex.h
>
> These are problematic because they are hard to maintain and do not support
> `O=` 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 absolute
> path to the source tree.
>
> Essentially, this is the automatic version of Tomonori's fix [1],
> suggested by Gary [2].
>
> Suggested-by: Gary Guo <[email protected]>
> Reported-by: FUJITA Tomonori <[email protected]>
> Closes: https://lore.kernel.org/r/[email protected] [1]
> Fixes: 48fadf440075 ("docs: Move rustdoc output, cross-reference it")
> Link: https://lore.kernel.org/rust-for-linux/20231026154525.6d14b495@eugeo/ [2]
> Signed-off-by: Miguel Ojeda <[email protected]>
> ---
> Documentation/rust/coding-guidelines.rst | 13 +++++++++++++
> rust/Makefile | 3 ++-
> rust/kernel/error.rs | 2 +-
> rust/kernel/ioctl.rs | 2 +-
> rust/kernel/kunit.rs | 2 +-
> rust/kernel/print.rs | 8 ++++----
> rust/kernel/sync/condvar.rs | 2 +-
> rust/kernel/sync/lock/mutex.rs | 2 +-
> rust/kernel/sync/lock/spinlock.rs | 2 +-
> rust/kernel/task.rs | 2 +-
> rust/kernel/workqueue.rs | 2 +-
> rust/macros/lib.rs | 2 +-
> 12 files changed, 28 insertions(+), 14 deletions(-)
>
> diff --git a/Documentation/rust/coding-guidelines.rst b/Documentation/rust/coding-guidelines.rst
> index aa8ed082613e..05542840b16c 100644
> [...]
> diff --git a/rust/Makefile b/rust/Makefile
> index 543b37f6c77f..73ea24117f07 100644
> --- a/rust/Makefile
> +++ b/rust/Makefile
> @@ -98,7 +98,8 @@ rustdoc: rustdoc-core rustdoc-macros rustdoc-compiler_builtins \
> $(Q)find $(rustdoc_output) -name '*.html' -type f -print0 | xargs -0 sed -Ei \
> -e 's:rust-logo-[0-9a-f]+\.svg:logo.svg:g' \
> -e 's:favicon-[0-9a-f]+\.svg:logo.svg:g' \
> - -e 's:<link rel="alternate icon" type="image/png" href="[/.]+/static\.files/favicon-(16x16|32x32)-[0-9a-f]+\.png">::g'
> + -e 's:<link rel="alternate icon" type="image/png" href="[/.]+/static\.files/favicon-(16x16|32x32)-[0-9a-f]+\.png">::g' \
> + -e 's:<a href="srctree/([^"]+)">:<a href="$(abs_srctree)/\1">:g'
Another way would be to not put `srctree` in the link and add
`abs_srctree` here to directories that are in `srctree`. But that might
be too wonky to rely on so this will be the way to go.
> $(Q)for f in $(rustdoc_output)/static.files/rustdoc-*.css; do \
> echo ".logo-container > img { object-fit: contain; }" >> $$f; done
>
> [...]
Reviewed-by: Martin Rodriguez Reboredo <[email protected]>
On 12/16/23 00:54, Miguel Ojeda wrote:
> 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/printk.h)
> /// [`struct mutex`]: ../../../../include/linux/mutex.h
>
> These are problematic because they are hard to maintain and do not support
> `O=` 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 absolute
> path to the source tree.
>
> Essentially, this is the automatic version of Tomonori's fix [1],
> suggested by Gary [2].
>
> Suggested-by: Gary Guo <[email protected]>
> Reported-by: FUJITA Tomonori <[email protected]>
> Closes: https://lore.kernel.org/r/[email protected] [1]
> Fixes: 48fadf440075 ("docs: Move rustdoc output, cross-reference it")
> Link: https://lore.kernel.org/rust-for-linux/20231026154525.6d14b495@eugeo/ [2]
> Signed-off-by: Miguel Ojeda <[email protected]>
This is nice.
Reviewed-by: Benno Lossin <[email protected]>
--
Cheers,
Benno
On Sat, Dec 16, 2023 at 12:54 AM Miguel Ojeda <[email protected]> wrote:
>
> 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/printk.h)
> /// [`struct mutex`]: ../../../../include/linux/mutex.h
>
> These are problematic because they are hard to maintain and do not support
> `O=` 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 absolute
> path to the source tree.
>
> Essentially, this is the automatic version of Tomonori's fix [1],
> suggested by Gary [2].
>
> Suggested-by: Gary Guo <[email protected]>
> Reported-by: FUJITA Tomonori <[email protected]>
> Closes: https://lore.kernel.org/r/[email protected] [1]
> Fixes: 48fadf440075 ("docs: Move rustdoc output, cross-reference it")
> Link: https://lore.kernel.org/rust-for-linux/20231026154525.6d14b495@eugeo/ [2]
> Signed-off-by: Miguel Ojeda <[email protected]>
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