From: Markus Heiser <markus.heiser@darmarIT.de>
To: corbet@lwn.net
Cc: jani.nikula@intel.com, daniel.vetter@ffwll.ch,
grant.likely@secretlab.ca, mchehab@osg.samsung.com,
keithp@keithp.com, linux-kernel@vger.kernel.org,
linux-doc@vger.kernel.org, hverkuil@xs4all.nl, "Heiser,
Markus" <markus.heiser@darmarIT.de>
Subject: [PATCH 0/7] add reST/sphinx-doc to linux documentation
Date: Mon, 6 Jun 2016 18:32:18 +0200 [thread overview]
Message-ID: <1465230745-31358-1-git-send-email-markus.heiser@darmarIT.de> (raw)
From: "Heiser, Markus" <markus.heiser@darmarIT.de>
Hi Jonathan, Jani, all -
I merged the work from sphkerneldoc POC [1], into branch (on v4.7-rc2)
git://github.com/return42/linux.git linux-doc-reST
The specification of the implementation is the (new) kernel-doc-HOWTO book which
is a part of the patch series (also online avaliable at [2]).
The kernel-doc-HOWTO book is a rewrite of the kernel-doc-nano-HOWTO.txt,
taking reST extension into account. It serves several purposes:
* user guide for kernel developers
* specification of the kernel-doc parser
* test case
The kernel_doc.py parser is a python implementation of the kernel-doc-HOWTO, the
kernel-doc perl script is not needed for reST builds. The python variant of the
kernel-doc parser supports the markup modes:
* kernel-doc (vintage)
* reST
This series also includes the reST directives describe in the kernel-doc-HOWTO:
* kernel-doc (uses/imports the parser from kernel_doc.py)
* flat-table (table notation with meaningfull diffs)
The Python/Sphinx extensions placed in the scripts/site-packages folder. With
this folder a minimal python infrastructure is provided.
The basic sphinx-build infrastructure consists of:
* Documentation/Makefile.reST & Documentation/conf.py
Makefile and basic 'sphinx config' file to build the various reST
documents and output formats. Provides the basic sphinx-doc build
infrastructure including the *sphinx-subprojects* feature. With this
feature each book can be build and distributed stand-alone.
* Documentation/books
In this folder, the books with reST markup are placed. To
provide *sphinx-subprojects*, each book has its one folder and
a (optional) Documentation/books/{book-name}.conf file
which *overwrites* the basic configuration from Documentation/conf.py
Any comments are welcome, but please read [2] first.
With regards
-- Markus --
[1] https://return42.github.io/sphkerneldoc
[2] https://return42.github.io/sphkerneldoc/books/kernel-doc-HOWTO
Heiser, Markus (7):
python: add scripts/site-packages
sphinx-doc: add basic sphinx-build infrastructure
kernel-doc-HOWTO: add kernel-doc specification
linuxdoc: add python package linuxdoc
kernel-doc parser: inital python implementation
kernel-doc directive: initial implementation
flat-table directive: initial implementation
Documentation/.gitignore | 2 +
Documentation/Makefile.reST | 111 +
Documentation/books/.gitignore | 0
Documentation/books/kernel-doc-HOWTO.conf | 200 ++
.../books/kernel-doc-HOWTO/all-in-a-tumble-src.rst | 12 +
.../books/kernel-doc-HOWTO/all-in-a-tumble.h | 271 ++
.../books/kernel-doc-HOWTO/all-in-a-tumble.rst | 11 +
Documentation/books/kernel-doc-HOWTO/csv_table.txt | 6 +
Documentation/books/kernel-doc-HOWTO/index.rst | 46 +
.../kernel-doc-HOWTO/kernel-doc-components.rst | 35 +
.../kernel-doc-HOWTO/kernel-doc-directive.rst | 199 ++
.../books/kernel-doc-HOWTO/kernel-doc-examples.rst | 16 +
.../books/kernel-doc-HOWTO/kernel-doc-intro.rst | 85 +
.../books/kernel-doc-HOWTO/kernel-doc-syntax.rst | 171 ++
.../kernel-doc-HOWTO/reST-kernel-doc-mode.rst | 120 +
Documentation/books/kernel-doc-HOWTO/refs.txt | 15 +
.../books/kernel-doc-HOWTO/table-markup.rst | 499 ++++
.../books/kernel-doc-HOWTO/test/parser_test.h | 332 +++
.../kernel-doc-HOWTO/vintage-kernel-doc-mode.rst | 100 +
Documentation/conf.py | 357 +++
Documentation/sphinx-static/theme_overrides.css | 45 +
Documentation/sphinx-tex/Makefile | 88 +
scripts/site-python/.gitignore | 1 +
scripts/site-python/README | 14 +
scripts/site-python/linuxdoc/__init__.py | 8 +
scripts/site-python/linuxdoc/kernel_doc.py | 2764 ++++++++++++++++++++
scripts/site-python/linuxdoc/rstFlatTable.py | 356 +++
scripts/site-python/linuxdoc/rstKernelDoc.py | 369 +++
28 files changed, 6233 insertions(+)
create mode 100644 Documentation/.gitignore
create mode 100644 Documentation/Makefile.reST
create mode 100644 Documentation/books/.gitignore
create mode 100644 Documentation/books/kernel-doc-HOWTO.conf
create mode 100644 Documentation/books/kernel-doc-HOWTO/all-in-a-tumble-src.rst
create mode 100644 Documentation/books/kernel-doc-HOWTO/all-in-a-tumble.h
create mode 100644 Documentation/books/kernel-doc-HOWTO/all-in-a-tumble.rst
create mode 100644 Documentation/books/kernel-doc-HOWTO/csv_table.txt
create mode 100644 Documentation/books/kernel-doc-HOWTO/index.rst
create mode 100644 Documentation/books/kernel-doc-HOWTO/kernel-doc-components.rst
create mode 100644 Documentation/books/kernel-doc-HOWTO/kernel-doc-directive.rst
create mode 100644 Documentation/books/kernel-doc-HOWTO/kernel-doc-examples.rst
create mode 100644 Documentation/books/kernel-doc-HOWTO/kernel-doc-intro.rst
create mode 100644 Documentation/books/kernel-doc-HOWTO/kernel-doc-syntax.rst
create mode 100644 Documentation/books/kernel-doc-HOWTO/reST-kernel-doc-mode.rst
create mode 100644 Documentation/books/kernel-doc-HOWTO/refs.txt
create mode 100644 Documentation/books/kernel-doc-HOWTO/table-markup.rst
create mode 100644 Documentation/books/kernel-doc-HOWTO/test/parser_test.h
create mode 100644 Documentation/books/kernel-doc-HOWTO/vintage-kernel-doc-mode.rst
create mode 100644 Documentation/conf.py
create mode 100644 Documentation/sphinx-static/theme_overrides.css
create mode 100644 Documentation/sphinx-tex/Makefile
create mode 100644 scripts/site-python/.gitignore
create mode 100644 scripts/site-python/README
create mode 100644 scripts/site-python/linuxdoc/__init__.py
create mode 100755 scripts/site-python/linuxdoc/kernel_doc.py
create mode 100755 scripts/site-python/linuxdoc/rstFlatTable.py
create mode 100755 scripts/site-python/linuxdoc/rstKernelDoc.py
--
v4.7-rc-2
next reply other threads:[~2016-06-06 16:35 UTC|newest]
Thread overview: 23+ messages / expand[flat|nested] mbox.gz Atom feed top
2016-06-06 16:32 Markus Heiser [this message]
2016-06-06 16:32 ` [PATCH 1/7] python: add scripts/site-packages Markus Heiser
2016-06-06 16:32 ` [PATCH 2/7] sphinx-doc: add basic sphinx-build infrastructure Markus Heiser
2016-06-06 16:32 ` [PATCH 3/7] kernel-doc-HOWTO: add kernel-doc specification Markus Heiser
2016-06-09 18:05 ` Randy Dunlap
2016-06-09 18:42 ` Jani Nikula
2016-06-10 16:00 ` Markus Heiser
2016-06-10 16:04 ` Randy Dunlap
2016-06-06 16:32 ` [PATCH 4/7] linuxdoc: add python package linuxdoc Markus Heiser
2016-06-06 16:32 ` [PATCH 5/7] kernel-doc parser: inital python implementation Markus Heiser
2016-06-06 16:32 ` [PATCH 6/7] kernel-doc directive: initial implementation Markus Heiser
2016-06-06 16:32 ` [PATCH 7/7] flat-table " Markus Heiser
2016-06-07 7:54 ` [PATCH 0/7] add reST/sphinx-doc to linux documentation Daniel Vetter
2016-06-07 8:59 ` Jani Nikula
2016-06-07 9:36 ` Markus Heiser
2016-06-07 11:09 ` Jani Nikula
2016-06-07 15:13 ` Markus Heiser
2016-06-07 9:14 ` Markus Heiser
2016-06-08 19:49 ` Jonathan Corbet
2016-06-10 15:25 ` Markus Heiser
2016-06-10 17:19 ` Jani Nikula
2016-06-15 13:01 ` Markus Heiser
2016-06-07 13:47 ` Markus Heiser
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=1465230745-31358-1-git-send-email-markus.heiser@darmarIT.de \
--to=markus.heiser@darmarit.de \
--cc=corbet@lwn.net \
--cc=daniel.vetter@ffwll.ch \
--cc=grant.likely@secretlab.ca \
--cc=hverkuil@xs4all.nl \
--cc=jani.nikula@intel.com \
--cc=keithp@keithp.com \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=mchehab@osg.samsung.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).