[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Message-ID: <20240818141200.386899-2-ojeda@kernel.org>
Date: Sun, 18 Aug 2024 16:12:00 +0200
From: Miguel Ojeda <ojeda@...nel.org>
To: Miguel Ojeda <ojeda@...nel.org>,
Alex Gaynor <alex.gaynor@...il.com>,
Wedson Almeida Filho <wedsonaf@...il.com>,
Jonathan Corbet <corbet@....net>
Cc: Boqun Feng <boqun.feng@...il.com>,
Gary Guo <gary@...yguo.net>,
Björn Roy Baron <bjorn3_gh@...tonmail.com>,
Benno Lossin <benno.lossin@...ton.me>,
Andreas Hindborg <a.hindborg@...sung.com>,
Alice Ryhl <aliceryhl@...gle.com>,
rust-for-linux@...r.kernel.org,
linux-doc@...r.kernel.org,
linux-kernel@...r.kernel.org,
patches@...ts.linux.dev,
Konstantin Ryabitsev <konstantin@...uxfoundation.org>
Subject: [PATCH 2/2] docs: rust: improve main page introducing a "Code documentation" section
Clean the "Rust" main page by introducing a 'Code documentation" section
to separate it from the rest of the text above.
In addition, introduce the "Rust code documentation" term, which may be
clearer than referring to a potentially unknown tool.
Furthermore, for the HTML case, homogenize both `rustdoc` and
non-`rustdoc` cases and use the term introduced above instead.
Then, always generate the pregenerated version part, since now there
is a section that is always generated and thus makes sense to do so.
Finally, finish the new section with a link to more details about the
Rust code documentation.
The intention is that:
- The non-HTML case mentions the code documentation too, making it
more prominent for readers of non-HTML docs.
- Both HTML cases read more naturally.
- The pregenerated version is always mentioned, since it is likely
useful for readers of non-HTML docs.
Signed-off-by: Miguel Ojeda <ojeda@...nel.org>
---
Documentation/rust/general-information.rst | 2 ++
Documentation/rust/index.rst | 19 +++++++++++++++----
2 files changed, 17 insertions(+), 4 deletions(-)
diff --git a/Documentation/rust/general-information.rst b/Documentation/rust/general-information.rst
index e174327ad361..357793f83c28 100644
--- a/Documentation/rust/general-information.rst
+++ b/Documentation/rust/general-information.rst
@@ -15,6 +15,8 @@ but not `std <https://doc.rust-lang.org/std/>`_. Crates for use in the
kernel must opt into this behavior using the ``#![no_std]`` attribute.
+.. _rust_code_documentation:
+
Code documentation
------------------
diff --git a/Documentation/rust/index.rst b/Documentation/rust/index.rst
index 5e51bfb248a4..55dcde9e9e7e 100644
--- a/Documentation/rust/index.rst
+++ b/Documentation/rust/index.rst
@@ -25,16 +25,27 @@ support is still in development/experimental, especially for certain kernel
configurations.
+Code documentation
+------------------
+
+Given a kernel configuration, the kernel may generate Rust code documentation,
+i.e. HTML rendered by the ``rustdoc`` tool.
+
.. only:: rustdoc and html
- You can also browse `rustdoc documentation <rustdoc/kernel/index.html>`_.
+ This kernel documentation was built with `Rust code documentation
+ <rustdoc/kernel/index.html>`_.
.. only:: not rustdoc and html
- This documentation does not include rustdoc generated information.
- A pregenerated version is provided at:
+ This kernel documentation was not built with Rust code documentation.
+
+A pregenerated version is provided at:
+
+ https://rust.docs.kernel.org
- https://rust.docs.kernel.org
+Please see the :ref:`Code documentation <rust_code_documentation>` section for
+more details.
.. toctree::
:maxdepth: 1
--
2.46.0
Powered by blists - more mailing lists