[PATCH v3 00/21] Create a book for Kernel development

* [PATCH v3 00/21] Create a book for Kernel development
@ 2016-09-14 11:06 Mauro Carvalho Chehab
  2016-09-14 11:06 ` [PATCH v3 01/21] doc: development-process: convert it to ReST markup Mauro Carvalho Chehab
                   ` (20 more replies)
  0 siblings, 21 replies; 40+ messages in thread
From: Mauro Carvalho Chehab @ 2016-09-14 11:06 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Markus Heiser,
	Jonathan Corbet, Jani Nikula, LKML

That's the third version of this series. Version 1 was submitted to
linux-doc only.

There are several documents related to Kernel development, where the
HOWTO works like an index to several such documents. There are also
a series of files describing the development process.

This patch series:

1) converts the Documentation/development-process/ to ReST
   and creates a Sphinx book, prepared to support sub-books;

2) Converts several files under Documentation (Changes, CodingStyle,
   HOWTO, ManagementStyle, SecurityBugs, SubmittingDrivers,
   SubmittingPatches, applying-patches.txt, kernel-docs.txt,
   stable_api_nonsense.txt, stable_kernel_rules.txt) to ReST markup;

3) Move the converted files to development-process/ directory, adding
   a .rst extension to them, adjusting cross-references and adding them
   to the development-process book.

NOTE: HOWTO also mentions the /README document on it. While IMHO it
makes sense to convert it to ReST, moving it out of the main directory
didn't sound a good idea. So, I'm leaving this one untouched.

PS.: I decided to do such conversion because I received yet  another
email from one developer wanted to submit drivers, but not being
aware of the right proceures. As usual, I pointed him to the Kernel
sources, but there are a way too much documentation there with a mix of
procedures and API docs inside.

It would be a way easier to point to a single URL where the submission
procedures would be altoghether. Hopefully, this will have a lot of time
in the future. My evil plan is to put this doc somewhere at LinuxTV and
have a standard e-mail prepared for such next requests :-D

The produced output, in HTML, is at:
	https://mchehab.fedorapeople.org/development-process/

The LaTeX version at:
	https://mchehab.fedorapeople.org/development-process/latex/development-process.tex

And the PDF version at:
	https://mchehab.fedorapeople.org/development-process/latex/development-process.pdf

--

Version 3 changes:

- Almost all changes here are just a patch set reordering to do first the 
  ReST conversion and then renames. Hopefully, Jon will be happier with
  such approach ;)
- Fixed some issues pointed by Joe Pershes at the CodingStyle conversion;
- Better explain the rationale for using ``foo`` instead of "foo" at
  CodingStyle.

Jani suggested to take the opportunity to standardize file name between
DocumentFoo, document-foo and document_foo. I opted to not do it
on this series, as we need first to agree on the convension. Once we have
some agreement, it should be easy to adjust the files to the agreed
nomenclature.

Version 2 changes:

- On version 1, I forgot to c/c LKML. Since v2, I'm c/c it, to give it a
  broader audience.
- Per Jonathan Corbet's suggestion, this version is placing all documents at
  the already existing developing-process/ directory, instead of creating a
  new dir;
- Also per Jon's suggestion, it also converts the development-process files
  to rst.
- Replaced all occurrences of the renamed files at the Kernel Documentation
  dir;
- Added conf.py and the need logic to produce both LaTeX and PDF output;

Mauro Carvalho Chehab (21):
  doc: development-process: convert it to ReST markup
  doc: development-process: rename files to rst
  docs-rst: create a book for the development process
  Documentation/HOWTO: convert to ReST notation
  Documentation/applying-patches.txt: convert it to ReST markup
  Documentation/Changes: convert it to ReST markup
  Documentation/CodingStyle: Convert to ReST markup
  Documentation/CodingStyle: use the proper tag for verbatim font
  Documentation/CodingStyle: replace underline markups
  Documentation/CodingStyle: use the .. note:: markup where needed
  Documentation/kernel-docs.txt: convert it to ReST markup
  Documentation/ManagementStyle: convert it to ReST markup
  Documentation/SecurityBugs: convert it to ReST markup
  Documentation/stable_api_nonsense.txt: convert it to ReST markup
  Documentation/stable_kernel_rules.txt: convert it to ReST markup
  Documentation/SubmittingDrivers: convert it to ReST markup
  Documentation/SubmittingPatches: convert it to ReST markup
  Documentation/HOWTO: add cross-references to other documents
  docs-rst: move HOWTO and mentioned documents to development-process/
  doc: adjust references to development-process
  doc-rst: Add the new development-process/ files to Sphinx build

 Documentation/ABI/README                           |   2 +-
 Documentation/BUG-HUNTING                          |   2 +-
 Documentation/DocBook/kernel-hacking.tmpl          |   4 +-
 Documentation/SubmitChecklist                      |   4 +-
 Documentation/adding-syscalls.txt                  |   2 +-
 Documentation/conf.py                              |   2 +
 .../development-process/{1.Intro => 1.Intro.rst}   |  68 +-
 .../{2.Process => 2.Process.rst}                   |  41 +-
 .../{3.Early-stage => 3.Early-stage.rst}           |  22 +-
 .../development-process/{4.Coding => 4.Coding.rst} |  48 +-
 .../{5.Posting => 5.Posting.rst}                   |  30 +-
 .../{6.Followthrough => 6.Followthrough.rst}       |  14 +-
 .../{7.AdvancedTopics => 7.AdvancedTopics.rst}     |  13 +-
 .../{8.Conclusion => 8.Conclusion.rst}             |   8 +-
 .../{Changes => development-process/Changes.rst}   | 226 +++---
 .../CodingStyle.rst}                               | 384 ++++++----
 .../{HOWTO => development-process/HOWTO.rst}       |  73 +-
 .../ManagementStyle.rst}                           | 152 ++--
 .../SecurityBugs.rst}                              |  14 +-
 .../SubmittingDrivers.rst}                         |  51 +-
 .../SubmittingPatches.rst}                         | 244 ++++---
 .../applying-patches.rst}                          | 312 ++++----
 Documentation/development-process/conf.py          |  10 +
 .../development-process/development-process.rst    |  27 +
 Documentation/development-process/index.rst        |  22 +
 Documentation/development-process/kernel-docs.rst  | 791 +++++++++++++++++++++
 .../stable_api_nonsense.rst}                       |  35 +-
 .../stable_kernel_rules.rst}                       | 107 ++-
 .../devicetree/bindings/submitting-patches.txt     |   2 +-
 Documentation/filesystems/locks.txt                |   2 +-
 Documentation/hwmon/submitting-patches             |   6 +-
 Documentation/index.rst                            |   1 +
 Documentation/isdn/README                          |   2 +-
 Documentation/ja_JP/HOWTO                          |  28 +-
 Documentation/ja_JP/SubmitChecklist                |   2 +-
 Documentation/ja_JP/SubmittingPatches              |  14 +-
 Documentation/ja_JP/stable_api_nonsense.txt        |   4 +-
 Documentation/ja_JP/stable_kernel_rules.txt        |   6 +-
 Documentation/kernel-docs.txt                      | 731 -------------------
 Documentation/ko_KR/HOWTO                          |  28 +-
 Documentation/ko_KR/stable_api_nonsense.txt        |   4 +-
 Documentation/networking/PLIP.txt                  |   2 +-
 Documentation/networking/netdev-FAQ.txt            |   8 +-
 Documentation/scsi/scsi_mid_low_api.txt            |   2 +-
 Documentation/virtual/kvm/review-checklist.txt     |   4 +-
 .../watchdog/convert_drivers_to_kernel_api.txt     |   2 +-
 Documentation/zh_CN/CodingStyle                    |   4 +-
 Documentation/zh_CN/HOWTO                          |  28 +-
 Documentation/zh_CN/SecurityBugs                   |   4 +-
 Documentation/zh_CN/SubmittingDrivers              |   8 +-
 Documentation/zh_CN/SubmittingPatches              |  10 +-
 Documentation/zh_CN/stable_api_nonsense.txt        |   4 +-
 Documentation/zh_CN/stable_kernel_rules.txt        |   6 +-
 MAINTAINERS                                        |   2 +-
 README                                             |   4 +-
 REPORTING-BUGS                                     |   2 +-
 drivers/net/ppp/Kconfig                            |   2 +-
 drivers/pcmcia/Kconfig                             |   2 +-
 fs/Kconfig.binfmt                                  |   2 +-
 fs/fuse/Kconfig                                    |   2 +-
 net/Kconfig                                        |   4 +-
 scripts/ver_linux                                  |   2 +-
 tools/testing/selftests/futex/README               |   2 +-
 63 files changed, 2120 insertions(+), 1524 deletions(-)
 rename Documentation/development-process/{1.Intro => 1.Intro.rst} (87%)
 rename Documentation/development-process/{2.Process => 2.Process.rst} (96%)
 rename Documentation/development-process/{3.Early-stage => 3.Early-stage.rst} (97%)
 rename Documentation/development-process/{4.Coding => 4.Coding.rst} (97%)
 rename Documentation/development-process/{5.Posting => 5.Posting.rst} (96%)
 rename Documentation/development-process/{6.Followthrough => 6.Followthrough.rst} (98%)
 rename Documentation/development-process/{7.AdvancedTopics => 7.AdvancedTopics.rst} (98%)
 rename Documentation/development-process/{8.Conclusion => 8.Conclusion.rst} (96%)
 rename Documentation/{Changes => development-process/Changes.rst} (56%)
 rename Documentation/{CodingStyle => development-process/CodingStyle.rst} (78%)
 rename Documentation/{HOWTO => development-process/HOWTO.rst} (96%)
 rename Documentation/{ManagementStyle => development-process/ManagementStyle.rst} (76%)
 rename Documentation/{SecurityBugs => development-process/SecurityBugs.rst} (92%)
 rename Documentation/{SubmittingDrivers => development-process/SubmittingDrivers.rst} (83%)
 rename Documentation/{SubmittingPatches => development-process/SubmittingPatches.rst} (85%)
 rename Documentation/{applying-patches.txt => development-process/applying-patches.rst} (68%)
 create mode 100644 Documentation/development-process/conf.py
 create mode 100644 Documentation/development-process/development-process.rst
 create mode 100644 Documentation/development-process/index.rst
 create mode 100644 Documentation/development-process/kernel-docs.rst
 rename Documentation/{stable_api_nonsense.txt => development-process/stable_api_nonsense.rst} (92%)
 rename Documentation/{stable_kernel_rules.txt => development-process/stable_kernel_rules.rst} (65%)
 delete mode 100644 Documentation/kernel-docs.txt

-- 
2.7.4

^ permalink raw reply	[flat|nested] 40+ messages in thread