From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752085AbcFFQf2 (ORCPT ); Mon, 6 Jun 2016 12:35:28 -0400 Received: from smtp3-1.goneo.de ([85.220.129.38]:46432 "EHLO smtp3-1.goneo.de" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1751660AbcFFQcw (ORCPT ); Mon, 6 Jun 2016 12:32:52 -0400 X-Spam-Flag: NO X-Spam-Score: -2.793 From: Markus Heiser 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" Subject: [PATCH 0/7] add reST/sphinx-doc to linux documentation Date: Mon, 6 Jun 2016 18:32:18 +0200 Message-Id: <1465230745-31358-1-git-send-email-markus.heiser@darmarIT.de> X-Mailer: git-send-email 2.7.4 Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org From: "Heiser, Markus" 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