[PATCH 0/7] add reST/sphinx-doc to linux documentation

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



From: "Heiser, Markus" <markus.heiser@xxxxxxxxxxx>

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

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html



[Index of Archives]     [Kernel Newbies]     [Security]     [Netfilter]     [Bugtraq]     [Linux FS]     [Yosemite Forum]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux RAID]     [Samba]     [Video 4 Linux]     [Device Mapper]     [Linux Resources]

  Powered by Linux