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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives
Hash Suite: Windows password security audit tool. GUI, reports in PDF.
[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Date:	Tue, 7 Jun 2016 15:47:29 +0200
From:	Markus Heiser <markus.heiser@...marit.de>
To:	corbet@....net
Cc:	corbet@....net, 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
Subject: Re: [PATCH 0/7] add reST/sphinx-doc to linux documentation

Hi all,

sorry I forgot to mentioning that I have not yet add the Makefile.reST
to the root Makefile. To test, please give the srctree environment in the
command line. E.g:

  cd /share/linux/Documentation
  srctree=/share/linux make -f Makefile.reST books/kernel-doc-HOWTO.html

-- Markus --



Am 06.06.2016 um 18:32 schrieb Markus Heiser <markus.heiser@...marIT.de>:

> 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
>