doc: rust: reorganize docs and coding

This separates the general information / concepts from the coding
guidelines.

Signed-off-by: Miguel Ojeda <ojeda@kernel.org>

Author: ojeda

Documentation/process/changes.rst

@@ -368,8 +368,9 @@ for details about Sphinx requirements.
 rustdoc
 -------
 
-``rustdoc`` is used to generate Rust documentation. Please see
-:ref:`Documentation/rust/docs.rst <rust_docs>` for more information.
+``rustdoc`` is used to generate the documentation for Rust code. Please see
+:ref:`Documentation/rust/general-information.rst <rust_general_information>`
+for more information.
 
 Getting updated software
 ========================

Documentation/rust/docs.rst renamed to Documentation/rust/coding-guidelines.rst

@@ -1,46 +1,55 @@
-.. _rust_docs:
+.. _rust_coding_guidelines:
 
-Docs
-====
+Coding Guidelines
+=================
 
-This document describes how to make the most out of the kernel documentation
-for Rust.
+This document describes how to write Rust code in the kernel.
 
-Rust kernel code is not documented like C kernel code (i.e. via kernel-doc).
-Instead, the usual system for documenting Rust code is used: the ``rustdoc``
-tool, which uses Markdown (a lightweight markup language).
 
-To learn Markdown, there are many guides available out there. For instance,
-the one at:
+Style & formatting
+------------------
 
-	https://commonmark.org/help/
+The code should be formatted using ``rustfmt``. In this way, a person
+contributing from time to time to the kernel does not need to learn and
+remember one more style guide. More importantly, reviewers and maintainers
+do not need to spend time pointing out style issues anymore, and thus
+less patch roundtrips may be needed to land a change.
+
+.. note:: Conventions on comments and documentation are not checked by
+  ``rustfmt``. Thus those are still needed to be taken care of.
 
+The default settings of ``rustfmt`` are used. This means the idiomatic Rust
+style is followed. For instance, 4 spaces are used for indentation rather
+than tabs.
 
-Reading the docs
-----------------
+It is convenient to instruct editors/IDEs to format while typing,
+when saving or at commit time. However, if for some reason reformatting
+the entire kernel Rust sources is needed at some point, the following can be
+run::
 
-The generated HTML docs produced by ``rustdoc`` include integrated search,
-linked items (e.g. types, functions, constants), source code, etc.
+	make LLVM=1 rustfmt
 
-The generated docs may be read at (TODO: link when in mainline and generated
-alongside the rest of the documentation):
+It is also possible to check if everything is formatted (printing a diff
+otherwise), for instance for a CI, with::
 
-	http://kernel.org/
+	make LLVM=1 rustfmtcheck
 
-The docs can also be easily generated and read locally. This is quite fast
-(same order as compiling the code itself) and no special tools or environment
-are needed. This has the added advantage that they will be tailored to
-the particular kernel configuration used. To generate them, use the ``rustdoc``
-target with the same invocation used for compilation, e.g.::
+Like ``clang-format`` for the rest of the kernel, ``rustfmt`` works on
+individual files, and does not require a kernel configuration. Sometimes it may
+even work with broken code.
 
-	make LLVM=1 rustdoc
 
-To read the docs locally in your web browser, run e.g.::
+Code documentation
+------------------
 
-	xdg-open rust/doc/kernel/index.html
+Rust kernel code is not documented like C kernel code (i.e. via kernel-doc).
+Instead, the usual system for documenting Rust code is used: the ``rustdoc``
+tool, which uses Markdown (a lightweight markup language).
 
-Writing the docs
-----------------
+To learn Markdown, there are many guides available out there. For instance,
+the one at:
+
+	https://commonmark.org/help/
 
 This is how a well-documented Rust function may look like::
 

Documentation/rust/coding.rst renamed to Documentation/rust/general-information.rst

@@ -1,43 +1,38 @@
-.. _rust_coding:
+.. _rust_general_information:
 
-Coding
-======
+General Information
+===================
 
-This document describes how to write Rust code in the kernel.
+This document contains useful information to know when working with
+the Rust support in the kernel.
 
 
-Coding style
-------------
+Code documentation
+------------------
 
-The code should be formatted using ``rustfmt``. In this way, a person
-contributing from time to time to the kernel does not need to learn and
-remember one more style guide. More importantly, reviewers and maintainers
-do not need to spend time pointing out style issues anymore, and thus
-less patch roundtrips may be needed to land a change.
+Rust kernel code is documented using ``rustdoc``, its built-in documentation
+generator.
 
-.. note:: Conventions on comments and documentation are not checked by
-  ``rustfmt``. Thus those are still needed to be taken care of: please see
-  :ref:`Documentation/rust/docs.rst <rust_docs>`.
+The generated HTML docs include integrated search, linked items (e.g. types,
+functions, constants), source code, etc. They may be read at (TODO: link when
+in mainline and generated alongside the rest of the documentation):
 
-The default settings of ``rustfmt`` are used. This means the idiomatic Rust
-style is followed. For instance, 4 spaces are used for indentation rather
-than tabs.
+	http://kernel.org/
 
-It is convenient to instruct editors/IDEs to format while typing,
-when saving or at commit time. However, if for some reason reformatting
-the entire kernel Rust sources is needed at some point, the following can be
-run::
+The docs can also be easily generated and read locally. This is quite fast
+(same order as compiling the code itself) and no special tools or environment
+are needed. This has the added advantage that they will be tailored to
+the particular kernel configuration used. To generate them, use the ``rustdoc``
+target with the same invocation used for compilation, e.g.::
 
-	make LLVM=1 rustfmt
+	make LLVM=1 rustdoc
 
-It is also possible to check if everything is formatted (printing a diff
-otherwise), for instance for a CI, with::
+To read the docs locally in your web browser, run e.g.::
 
-	make LLVM=1 rustfmtcheck
+	xdg-open rust/doc/kernel/index.html
 
-Like ``clang-format`` for the rest of the kernel, ``rustfmt`` works on
-individual files, and does not require a kernel configuration. Sometimes it may
-even work with broken code.
+To learn about how to write the documentation, please see the coding guidelines
+at :ref:`Documentation/rust/coding-guidelines.rst <rust_coding_guidelines>`.
 
 
 Extra lints
@@ -83,9 +78,3 @@ configuration:
 	#[cfg(CONFIG_X="y")]   // Enabled as a built-in (`y`)
 	#[cfg(CONFIG_X="m")]   // Enabled as a module   (`m`)
 	#[cfg(not(CONFIG_X))]  // Disabled
-
-
-Documentation
--------------
-
-Please see :ref:`Documentation/rust/docs.rst <rust_docs>`.

Documentation/rust/index.rst

@@ -9,8 +9,8 @@ in the kernel, please read the
     :maxdepth: 1
 
     quick-start
-    coding
-    docs
+    general-information
+    coding-guidelines
     arch-support
 
 .. only::  subproject and html

Documentation/rust/quick-start.rst

@@ -113,7 +113,7 @@ rustfmt
 
 The ``rustfmt`` tool is used to automatically format all the Rust kernel code,
 including the generated C bindings (for details, please see
-:ref:`Documentation/rust/coding.rst <rust_coding>`).
+:ref:`Documentation/rust/coding-guidelines.rst <rust_coding_guidelines>`).
 
 If ``rustup`` is being used, its ``default`` profile already installs the tool,
 thus nothing needs to be done. If another profile is being used, the component
@@ -129,7 +129,7 @@ clippy
 
 ``clippy`` is a Rust linter. Running it provides extra warnings for Rust code.
 It can be run by passing ``CLIPPY=1`` to ``make`` (for details, please see
-:ref:`Documentation/rust/coding.rst <rust_coding>`).
+:ref:`Documentation/rust/general-information.rst <rust_general_information>`).
 
 If ``rustup`` is being used, its ``default`` profile already installs the tool,
 thus nothing needs to be done. If another profile is being used, the component
@@ -159,7 +159,7 @@ rustdoc
 
 ``rustdoc`` is the documentation tool for Rust. It generates pretty HTML
 documentation for Rust code (for details, please see
-:ref:`Documentation/rust/docs.rst <rust_docs>`).
+:ref:`Documentation/rust/general-information.rst <rust_general_information>`).
 
 ``rustdoc`` is also used to test the examples provided in documented Rust code
 (called doctests or documentation tests). The ``rusttest`` Make target uses