rust: support `srctree`-relative links
Subsystems (5)
Miguel Ojeda
maintainerPATCH 1/1 rust: support `srctree`-relative links
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.hThese 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.hThe 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].
--- 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(-)
Documentation/rust/coding-guidelines.rst +13 -0
@@ -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 ------
rust/Makefile +2 -1
@@ -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
rust/kernel/error.rs +1 -1
@@ -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 ;
rust/kernel/ioctl.rs +1 -1
@@ -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)]
rust/kernel/kunit.rs +1 -1
@@ -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>
rust/kernel/print.rs +4 -4
@@ -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 <'_>) {
rust/kernel/sync/condvar.rs +1 -1
@@ -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]
rust/kernel/sync/lock/mutex.rs +1 -1
@@ -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.
rust/kernel/sync/lock/spinlock.rs +1 -1
@@ -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.
rust/kernel/task.rs +1 -1
@@ -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};
rust/kernel/workqueue.rs +1 -1
@@ -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 ;
rust/macros/lib.rs +1 -1
@@ -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
Signature · 1 line
2.43.0
Quoted 2 lines · Miguel Ojeda
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
Quoted 49 lines · Miguel Ojeda
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.hThese 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.hThe links are fixed after
rustdocgeneration 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]>Fixes 48fadf440075 ("docs: Move rustdoc output, cross-reference it")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(-)Documentation/rust/coding-guidelines.rst +0
-0rust/Makefile +0
-0
rust/Makefile rustdoc: rustdoc-core rustdoc-macros rustdoc-compiler_builtins \ · line 102
Quoted 6 lines
rust/Makefile +2
-1@@ -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.
rust/Makefile rustdoc: rustdoc-core rustdoc-macros rustdoc-compiler_builtins \ · line 105
Quoted 4 lines
rust/Makefile +0
-0$(Q)for f in $(rustdoc_output)/static.files/rustdoc-*.css; do \ echo ".logo-container > img { object-fit: contain; }" >> $$f; done
Quoted 20 lines · Miguel Ojeda
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.hThese 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.hThe links are fixed after
rustdocgeneration 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].
Quoted 6 lines
Suggested-by Gary Guo <[email protected]>Reported-by FUJITA Tomonori <[email protected]>Fixes 48fadf440075 ("docs: Move rustdoc output, cross-reference it")Signed-off-by Miguel Ojeda <[email protected]>
This is nice.
Signature · 2 lines
Cheers, Benno
Miguel Ojeda
AppliedQuoted 21 lines · Miguel Ojeda
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.hThese 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.hThe links are fixed after
rustdocgeneration 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].
Quoted 6 lines
Suggested-by Gary Guo <[email protected]>Reported-by FUJITA Tomonori <[email protected]>Fixes 48fadf440075 ("docs: Move rustdoc output, cross-reference it")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