[<prev] [next>] [thread-next>] [day] [month] [year] [list]
Date: Mon, 6 Jun 2016 18:32:18 +0200
From: Markus Heiser <markus.heiser@...marIT.de>
To: corbet@....net
Cc: jani.nikula@...el.com, daniel.vetter@...ll.ch,
grant.likely@...retlab.ca, mchehab@....samsung.com,
keithp@...thp.com, linux-kernel@...r.kernel.org,
linux-doc@...r.kernel.org, hverkuil@...all.nl,
"Heiser, Markus" <markus.heiser@...marIT.de>
Subject: [PATCH 0/7] add reST/sphinx-doc to linux documentation
From: "Heiser, Markus" <markus.heiser@...marIT.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
Powered by blists - more mailing lists