[PATCH 2/2] docs: rust: improve main page introducing a "Code documentation" section

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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@xxxxxxxxxx>
---
 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





[Index of Archives]     [Kernel Newbies]     [Security]     [Netfilter]     [Bugtraq]     [Linux FS]     [Yosemite Forum]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux RAID]     [Samba]     [Video 4 Linux]     [Device Mapper]     [Linux Resources]

  Powered by Linux