From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S932725AbcFGNrw (ORCPT ); Tue, 7 Jun 2016 09:47:52 -0400 Received: from smtp2.goneo.de ([85.220.129.33]:50352 "EHLO smtp2.goneo.de" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1754909AbcFGNru convert rfc822-to-8bit (ORCPT ); Tue, 7 Jun 2016 09:47:50 -0400 X-Spam-Flag: NO X-Spam-Score: -2.783 Content-Type: text/plain; charset=us-ascii Mime-Version: 1.0 (Mac OS X Mail 6.6 \(1510\)) Subject: Re: [PATCH 0/7] add reST/sphinx-doc to linux documentation From: Markus Heiser In-Reply-To: <1465230745-31358-1-git-send-email-markus.heiser@darmarIT.de> Date: Tue, 7 Jun 2016 15:47:29 +0200 Cc: corbet@lwn.net, 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 Content-Transfer-Encoding: 8BIT Message-Id: References: <1465230745-31358-1-git-send-email-markus.heiser@darmarIT.de> To: corbet@lwn.net X-Mailer: Apple Mail (2.1510) Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org 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 : > 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 >