[PATCH 03/17] docs-rst: add inter-document cross references
From: Mauro Carvalho Chehab
Date: Thu Sep 22 2016 - 07:51:09 EST
Add cross references for the development process documents
that were converted to ReST:
Documentation/SubmitChecklist
Documentation/SubmittingDrivers
Documentation/SubmittingPatches
Documentation/development-process/development-process.rst
Documentation/stable_kernel_rules.txt
Signed-off-by: Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx>
---
Documentation/SubmitChecklist | 10 +++++----
Documentation/SubmittingDrivers | 7 ++++---
Documentation/SubmittingPatches | 24 ++++++++++++++--------
.../development-process/development-process.rst | 2 ++
Documentation/stable_kernel_rules.txt | 7 +++++--
5 files changed, 32 insertions(+), 18 deletions(-)
diff --git a/Documentation/SubmitChecklist b/Documentation/SubmitChecklist
index 22a370ff34e5..894289b22b15 100644
--- a/Documentation/SubmitChecklist
+++ b/Documentation/SubmitChecklist
@@ -1,3 +1,5 @@
+.. _submitchecklist:
+
Linux Kernel patch submission checklist
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -5,7 +7,7 @@ Here are some basic things that developers should do if they want to see their
kernel patch submissions accepted more quickly.
These are all above and beyond the documentation that is provided in
-Documentation/SubmittingPatches
+:ref:`Documentation/SubmittingPatches <submittingpatches>`
and elsewhere regarding submitting Linux kernel patches.
@@ -28,8 +30,8 @@ and elsewhere regarding submitting Linux kernel patches.
4) ppc64 is a good architecture for cross-compilation checking because it
tends to use ``unsigned long`` for 64-bit quantities.
-5: Check your patch for general style as detailed in
- Documentation/CodingStyle.
+5) Check your patch for general style as detailed in
+ :ref:`Documentation/CodingStyle <codingstyle>`.
Check for trivial violations with the patch style checker prior to
submission (``scripts/checkpatch.pl``).
You should be able to justify all violations that remain in
@@ -54,7 +56,7 @@ and elsewhere regarding submitting Linux kernel patches.
but any one function that uses more than 512 bytes on the stack is a
candidate for change.
-11: Include :ref:`kernel-doc <kernel_doc>` to document global kernel APIs.
+11) Include :ref:`kernel-doc <kernel_doc>` to document global kernel APIs.
(Not required for static functions, but OK there also.) Use
``make htmldocs`` or ``make pdfdocs`` to check the
:ref:`kernel-doc <kernel_doc>` and fix any issues.
diff --git a/Documentation/SubmittingDrivers b/Documentation/SubmittingDrivers
index 2ac931645e53..252b77a23fad 100644
--- a/Documentation/SubmittingDrivers
+++ b/Documentation/SubmittingDrivers
@@ -40,9 +40,9 @@ Linux 2.4:
maintainer does not respond or you cannot find the appropriate
maintainer then please contact Willy Tarreau <w@xxxxxx>.
-Linux 2.6:
+Linux 2.6 and upper:
The same rules apply as 2.4 except that you should follow linux-kernel
- to track changes in API's. The final contact point for Linux 2.6
+ to track changes in API's. The final contact point for Linux 2.6+
submissions is Andrew Morton.
What Criteria Determine Acceptance
@@ -73,7 +73,8 @@ Interfaces:
Code:
Please use the Linux style of code formatting as documented
- in Documentation/CodingStyle. If you have sections of code
+ in :ref:`Documentation/CodingStyle <codingStyle>`.
+ If you have sections of code
that need to be in other formats, for example because they
are shared with a windows driver kit and you want to
maintain them just once separate them out nicely and note
diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 9c3dfa7babf3..36f1dedc944c 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -10,10 +10,12 @@ can greatly increase the chances of your change being accepted.
This document contains a large number of suggestions in a relatively terse
format. For detailed information on how the kernel development process
-works, see Documentation/development-process. Also, read
-Documentation/SubmitChecklist for a list of items to check before
+works, see :ref:`Documentation/development-process <development_process_main>`.
+Also, read :ref:`Documentation/SubmitChecklist <submitchecklist>`
+for a list of items to check before
submitting code. If you are submitting a driver, also read
-Documentation/SubmittingDrivers; for device tree binding patches, read
+:ref:`Documentation/SubmittingDrivers <submittingdrivers>`;
+for device tree binding patches, read
Documentation/devicetree/bindings/submitting-patches.txt.
Many of these steps describe the default behavior of the ``git`` version
@@ -235,7 +237,9 @@ then only post say 15 or so at a time and wait for review and integration.
---------------------------
Check your patch for basic style violations, details of which can be
-found in Documentation/CodingStyle. Failure to do so simply wastes
+found in
+:ref:`Documentation/CodingStyle <codingstyle>`.
+Failure to do so simply wastes
the reviewers time and will get your patch rejected, probably
without even being read.
@@ -300,8 +304,9 @@ toward the stable maintainers by putting a line like this::
Cc: stable@xxxxxxxxxxxxxxx
into the sign-off area of your patch (note, NOT an email recipient). You
-should also read Documentation/stable_kernel_rules.txt in addition to this
-file.
+should also read
+:ref:`Documentation/stable_kernel_rules.txt <stable_kernel_rules>`
+in addition to this file.
Note, however, that some subsystem maintainers want to come to their own
conclusions on which patches should go to the stable trees. The networking
@@ -358,8 +363,9 @@ decreasing the likelihood of your MIME-attached change being accepted.
Exception: If your mailer is mangling patches then someone may ask
you to re-send them using MIME.
-See Documentation/email-clients.txt for hints about configuring
-your e-mail client so that it sends your patches untouched.
+See :ref:`Documentation/email-clients.txt <email_clients>`
+for hints about configuring your e-mail client so that it sends your patches
+untouched.
7) E-mail size
--------------
@@ -823,7 +829,7 @@ NO!!!! No more huge patch bombs to linux-kernel@xxxxxxxxxxxxxxx people!
<https://lkml.org/lkml/2005/7/11/336>
Kernel Documentation/CodingStyle:
- <Documentation/CodingStyle>
+ :ref:`Documentation/CodingStyle <codingstyle>`
Linus Torvalds's mail on the canonical patch format:
<http://lkml.org/lkml/2005/4/7/183>
diff --git a/Documentation/development-process/development-process.rst b/Documentation/development-process/development-process.rst
index d431a1098875..bd1399f7202a 100644
--- a/Documentation/development-process/development-process.rst
+++ b/Documentation/development-process/development-process.rst
@@ -1,3 +1,5 @@
+.. _development_process_main:
+
A guide to the Kernel Development Process
=========================================
diff --git a/Documentation/stable_kernel_rules.txt b/Documentation/stable_kernel_rules.txt
index 1eba72708c7f..4d82e31b7958 100644
--- a/Documentation/stable_kernel_rules.txt
+++ b/Documentation/stable_kernel_rules.txt
@@ -26,7 +26,9 @@ Rules on what kind of patches are accepted, and which ones are not, into the
race can be exploited is also provided.
- It cannot contain any "trivial" fixes in it (spelling changes,
whitespace cleanups, etc).
- - It must follow the Documentation/SubmittingPatches rules.
+ - It must follow the
+ :ref:`Documentation/SubmittingPatches <submittingpatches>`
+ rules.
- It or an equivalent fix must already exist in Linus' tree (upstream).
@@ -37,7 +39,8 @@ Procedure for submitting patches to the -stable tree
submission guidelines as described in
Documentation/networking/netdev-FAQ.txt
- Security patches should not be handled (solely) by the -stable review
- process but should follow the procedures in Documentation/SecurityBugs.
+ process but should follow the procedures in
+ :ref:`Documentation/SecurityBugs <securitybugs>`.
For all other submissions, choose one of the following procedures
-----------------------------------------------------------------
--
2.7.4