[PATCH v4 00/29] Create a book for Kernel development

* [PATCH v4 00/29] Create a book for Kernel development
@ 2016-09-19 11:07 Mauro Carvalho Chehab
  2016-09-19 11:07 ` [PATCH v4 01/29] doc-rst: add CSS styles for :kbd: and :menuselection: Mauro Carvalho Chehab
                   ` (28 more replies)
  0 siblings, 29 replies; 33+ messages in thread
From: Mauro Carvalho Chehab @ 2016-09-19 11:07 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Markus Heiser,
	Jonathan Corbet, Jani Nikula, LKML, Greg KH

That's the 4th version of this series. It also contains a second patch series
with more ReST conversions and documentation improvements.
This patchset merges the content of a second patch series:

	[PATCH 00/17] Improve documentation for the development-process

I opted to keep the patch changing the  kernel-docs.txt changes
(patch 21/29). The patch is already written and another patch
(patch 22/29)  depends on it, because there are references to
this file at Documentation/HOWTO.

It shouldn't be hard  to get rid of it, but I'm not sure if worths
the effort. As I commented, people might find useful to update
it to point to more modern documents. If people won't do it,
it can still be removed from the Kernel a the next Kernel version.

Yet, if you prefer, feel free to drop patch 21/29 and replace
by a patch removing kernel-docs.txt, adding my ack.

I also folded all renaming stuff to a single patch (29/29).

Jon,

   Please don't merge patch 29/29 as-is, as it requires more discussion.

I opted to not rename development-process there, nor to split it into
per-subsystem changes, as we need to first agree about the approach to
be taken. I opted to keep this at the series to allow people to test the
book generation, on both pdf and html formats.

IMHO, patches 1 to 28 should be OK to merge, as they don't do any
renames. We need to discuss more about patch 29, until we solve
this question:
	"Should we rename those well-known documents?"

If the answer is "no":

  - should we use symlinks instead?
  - can't Sphinx be tricked to build them with their existing names?

If the answer is "yes":

  - shoud we create files to replace CheckPatch/SubmitPatches/SubmitDrivers
    that would point to the newer location?

Also, as you pointed, some of those files (like SecurityBugs) may fit better
on a "users manual" book.

For such book, we'll likely want to group most of the information at
the /README file, and add other stuff there too, like:

	Documentation/kernel-parameters.txt
	(perhaps splitting its content per-subystem?)

Also, as SecurityBooks is mentioned at HOWTO, if we put it on a separate
book, we'll need to enable interSphinx extension, in order to generate
cross-references between different documents. This is needed for the PDF
output.

Also, "development-process" is a very big name for a dir. We should likely
shorten it to just "process" or "devel". (and "Documentation/" is another
big name too). Those two big names makes several cross-references to
be bigger than the 80-cols limit, like:

	:ref:`Documentation/development-process/SubmittingDrivers.rst <submittingdrivers>`

--

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 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 4 changes:

- Keep chapter numeration on the Documentation/* files (CodingStyle
  & friends);
- Use :: on the same line, to improve document reading in plain text;
- Added the contents of a separate patch series:

	[PATCH 00/17] Improve documentation for the development-process

  Several patches from such series were folded on the ReST conversion
  patches.

  Ok, this makes this one big, but it helped to keep some sanity, as
  all renames could be folded into a single patch at the end of this
  series.

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 (29):
  doc-rst: add CSS styles for :kbd: and :menuselection:
  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/applying-patches.txt: Update the information there
  Documentation/Changes: convert it to ReST markup
  Documentation/Changes: add minimal requirements for documentation
    build
  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/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/SubmittingPatches: enrich the Sphinx output
  Documentation/kernel-docs.txt: convert it to ReST markup
  Documentation/HOWTO: add cross-references to other documents
  Documentation/HOWTO: update information about generating documentation
  Documentation/HOWTO: improve some markups to make it visually better
  Documentation/HOWTO: adjust external link references
  Documentation/SubmitChecklist: update kernel-doc task
  Documentation/SubmitChecklist: convert it to ReST markup
  Documentation/email-clients.txt: convert it to ReST markup
  docs-rst: move HOWTO and mentioned documents to development-process/

 Documentation/ABI/README                           |   2 +-
 Documentation/BUG-HUNTING                          |   2 +-
 Documentation/DocBook/kernel-hacking.tmpl          |   4 +-
 Documentation/SubmitChecklist                      | 109 ---
 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}                   |  32 +-
 .../{6.Followthrough => 6.Followthrough.rst}       |  14 +-
 .../{7.AdvancedTopics => 7.AdvancedTopics.rst}     |  13 +-
 .../{8.Conclusion => 8.Conclusion.rst}             |   8 +-
 .../{Changes => development-process/Changes.rst}   | 262 ++++---
 .../CodingStyle.rst}                               | 387 ++++++----
 .../{HOWTO => development-process/HOWTO.rst}       | 156 ++--
 .../ManagementStyle.rst}                           | 154 ++--
 .../SecurityBugs.rst}                              |   8 +
 .../development-process/SubmitChecklist.rst        | 120 ++++
 .../SubmittingDrivers.rst}                         |  56 +-
 .../SubmittingPatches.rst}                         | 314 ++++----
 .../applying-patches.rst}                          | 427 ++++++-----
 Documentation/development-process/conf.py          |  10 +
 .../development-process/development-process.rst    |  29 +
 .../email-clients.rst}                             | 216 +++---
 Documentation/development-process/index.rst        |  29 +
 Documentation/development-process/kernel-docs.rst  | 791 +++++++++++++++++++++
 .../stable_api_nonsense.rst}                       |  37 +-
 .../stable_kernel_rules.rst}                       | 110 ++-
 .../devicetree/bindings/submitting-patches.txt     |   2 +-
 Documentation/filesystems/locks.txt                |   2 +-
 Documentation/hwmon/submitting-patches             |   8 +-
 Documentation/index.rst                            |   1 +
 Documentation/isdn/README                          |   2 +-
 Documentation/ja_JP/HOWTO                          |  28 +-
 Documentation/ja_JP/SubmitChecklist                |   6 +-
 Documentation/ja_JP/SubmittingPatches              |  18 +-
 Documentation/ja_JP/stable_api_nonsense.txt        |   4 +-
 Documentation/ja_JP/stable_kernel_rules.txt        |   6 +-
 Documentation/kernel-docs.txt                      | 731 -------------------
 Documentation/kernel-documentation.rst             |   2 +
 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/sphinx-static/theme_overrides.css    |  15 +-
 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              |  12 +-
 Documentation/zh_CN/email-clients.txt              |   4 +-
 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 +-
 68 files changed, 2544 insertions(+), 1898 deletions(-)
 delete mode 100644 Documentation/SubmitChecklist
 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} (51%)
 rename Documentation/{CodingStyle => development-process/CodingStyle.rst} (78%)
 rename Documentation/{HOWTO => development-process/HOWTO.rst} (88%)
 rename Documentation/{ManagementStyle => development-process/ManagementStyle.rst} (75%)
 rename Documentation/{SecurityBugs => development-process/SecurityBugs.rst} (94%)
 create mode 100644 Documentation/development-process/SubmitChecklist.rst
 rename Documentation/{SubmittingDrivers => development-process/SubmittingDrivers.rst} (82%)
 rename Documentation/{SubmittingPatches => development-process/SubmittingPatches.rst} (78%)
 rename Documentation/{applying-patches.txt => development-process/applying-patches.rst} (52%)
 create mode 100644 Documentation/development-process/conf.py
 create mode 100644 Documentation/development-process/development-process.rst
 rename Documentation/{email-clients.txt => development-process/email-clients.rst} (56%)
 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} (91%)
 rename Documentation/{stable_kernel_rules.txt => development-process/stable_kernel_rules.rst} (64%)
 delete mode 100644 Documentation/kernel-docs.txt

-- 
2.7.4

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