From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1762051AbcINLR7 (ORCPT ); Wed, 14 Sep 2016 07:17:59 -0400 Received: from bombadil.infradead.org ([198.137.202.9]:40231 "EHLO bombadil.infradead.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1761463AbcINLM5 (ORCPT ); Wed, 14 Sep 2016 07:12:57 -0400 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , Mauro Carvalho Chehab , Markus Heiser , Jonathan Corbet , Jani Nikula , LKML Subject: [PATCH v3 00/21] Create a book for Kernel development Date: Wed, 14 Sep 2016 08:06:29 -0300 Message-Id: X-Mailer: git-send-email 2.7.4 Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org 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