[PATCH v3 00/21] Create a book for Kernel development
From: Mauro Carvalho Chehab
Date: Wed Sep 14 2016 - 07:18:17 EST
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