Re: [PATCH] docs-rst: add inter-document cross references

[Mauro Carvalho Chehab]

Hi Jon,

Em Wed, 21 Sep 2016 15:44:05 -0600
Jonathan Corbet  escreveu:

> ...and now I'm thinking that's maybe about enough in docs for 4.9...:)

I finished handling the plain text files that, IMHO, should be on
either user of development process books. 

As you're feeling that there are enough material for 4.9, I'll
postpone their submission to early during 4.10-rc time.

Anyway, if you want to take a sneak pick, the patches are in this tree:

https://git.linuxtv.org//mchehab/experimental.git/log/?h=lkml-books

and the html books are at:
https://mchehab.fedorapeople.org/user/
https://mchehab.fedorapeople.org/development-process/

ePub at:
https://mchehab.fedorapeople.org/user/epub/
https://mchehab.fedorapeople.org/development-process/epub/

PDF and LaTex at:
https://mchehab.fedorapeople.org/user/latex/
https://mchehab.fedorapeople.org/development-process/latex/

Probably, there will be issues with PDF, as Sphinx usually require manual
work to fix issues with PDF output, and on several cases, raw LaTeX
commands inside the rst files. I also had to patch a LaTeX config locally
to avoid an out of memory error when building the user's book.

The last patch in this tree is the RFC patch that adds MAINTAINERS file
to the user's book.

In total, 42 files were converted to either one of the books, 
of a total of 151 files at Documentation/, plus 2 files at /.

There, I opted to use symlinks instead of moving files. There is an
issue with that, though: it is harder to identify what files are
part of the Sphinx build, and what files aren't. Ok, we could
write some sort of script to identify the undocumented files, but
this is a way more complex that doing a
$ find . -maxdepth 1 -type f

(or doing a ls there and see the files inside it)

So, IMHO, we should be moving the files instead of symlinking them.


Thanks,
Mauro

--

The following changes since commit 17e9217d41e18293c82772b4da544f25e62c342e:

  Merge branch 'doc/4.9' into docs-next (2016-09-21 15:55:06 -0600)

are available in the git repository at:

  git://linuxtv.org/mchehab/experimental.git lkml-books

for you to fetch changes up to c8b07684c0278d7f9d0e30f575eb4be3a2da4c3b:

  docs-rst: user: add MAINTAINERS (2016-09-23 17:39:01 -0300)


Mauro Carvalho Chehab (33):
  Documentation/applying-patches.txt: fix a bad external link
  REPORTING-BUGS: convert to ReST markup
  README: convert it to ReST markup
  Documentation/kernel-parameters.txt: convert to ReST markup
  docs-rst: add documents to development-process
  docs-rst: create an user's manual book
  Documentation/adding-syscalls.txt: convert it to ReST markup
  Documentation/bad_memory.txt: convert it to ReST markup
  Documentation/basic_profiling.rst: convert to ReST markup
  Documentation/binfmt_misc.txt: convert it to ReST markup
  Documentation/serial-console.txt: convert it to ReST markup
  Documentation/braille-console: convert it to ReST markup
  Documentation/BUG-HUNTING: convert to ReST markup
  Documentation/CodeOfConflict: add it to the development-process book
  Documentation/devices.rst: convert it to ReST markup
  Documentation/dynamic-debug-howto.txt: convert it to ReST markup
  Documentation/initrd.txt: convert to ReST markup
  Documentation/init.txt: convert to ReST markup
  Documentation/magic-number.txt: convert it to ReST markup
  Documentation/md.txt: Convert to ReST markup
  Documentation/module-signing.txt: convert to ReST markup
  Documentation/mono.txt: convert to ReST markup
  Documentation/java.txt: convert to ReST markup
  Documentation/oops-tracing.txt: convert to ReST markup
  Documentation/parport.txt: convert to ReST markup
  Documentation/ramoops.txt: convert it to ReST format
  Documentation/sysfs-rules.txt: convert it to ReST markup
  Documentation/sysrq.txt: convert to ReST markup
  Documentation/unicode.txt: convert it to ReST markup
  Documentation/VGA-softcursor.txt: convert to ReST markup
  Documentation/volatile-considered-harmful.txt: convert to ReST markup
  Documentation/parport.txt: fix table to show on LaTeX
  docs-rst: user: add MAINTAINERS

 Documentation/BUG-HUNTING  |  164 +--
 Documentation/CodeOfConflict   |1 +
 Documentation/SecurityBugs |   12 +-
 Documentation/VGA-softcursor.txt   |   73 +-
 Documentation/adding-syscalls.txt  |  269 ++---
 Documentation/applying-patches.txt |2 +-
 Documentation/bad_memory.txt   |   26 +-
 Documentation/basic_profiling.txt  |   59 +-
 Documentation/binfmt_misc.txt  |  134 ++-
 Documentation/braille-console.txt  |   30 +-
 Documentation/conf.py 

Re: [PATCH] docs-rst: add inter-document cross references

[Jonathan Corbet]

On Wed, 21 Sep 2016 08:51:05 -0300
Mauro Carvalho Chehab  wrote:

> 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

Applied, thanks.

...and now I'm thinking that's maybe about enough in docs for 4.9...:)

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] docs-rst: add inter-document cross references

[Greg Kroah-Hartman]

On Wed, Sep 21, 2016 at 08:51:05AM -0300, Mauro Carvalho Chehab wrote:
> 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 
> ---
> 
> The changes here were at patch 29/29, that did the rename. I opted to
> split this change to just add the cross-references without the rename, as
> it makes easier if we decide to use symlinks instead of renames.
> 
> As I rebased the rename patch as well, on the top of this one, we can
> also use the rename, if people find it better.

For the stable_kernel_rules.txt portion:

Acked-by: Greg Kroah-Hartman 
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH] docs-rst: add inter-document cross references

[Mauro Carvalho Chehab]

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

The changes here were at patch 29/29, that did the rename. I opted to
split this change to just add the cross-references without the rename, as
it makes easier if we decide to use symlinks instead of renames.

As I rebased the rename patch as well, on the top of this one, we can
also use the rename, if people find it better.

 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 `
 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 `.
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 ` to document global  kernel APIs.
+11) Include :ref:`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 ` 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 .
 
-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 `.
+   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 `.
+Also, read :ref:`Documentation/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 `;
+for device tree binding patches, read
 Documentation/devicetree/bindings/submitting-patches.txt.