linux/Documentation/sphinx/kernel-doc.py, branch v4.9

docs: sphinx-extensions: add metadata parallel-safe

2016-09-01T14:19:02Z

The setup() function of a Sphinx-extension can return a dictionary. This is treated by Sphinx as metadata of the extension [1]. With metadata "parallel_read_safe = True" a extension is marked as save for "parallel reading of source". This is needed if you want build in parallel with N processes. E.g.: make SPHINXOPTS=-j4 htmldocs will no longer log warnings like: WARNING: the foobar extension does not declare if it is safe for parallel reading, assuming it isn't - please ask the extension author to check and make it explicit. Add metadata to extensions: * kernel-doc * flat-table * kernel-include [1] http://www.sphinx-doc.org/en/stable/extdev/#extension-metadata Signed-off-by: Markus Heiser Tested-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet

doc-rst: kernel-doc directive, fix state machine reporter

2016-07-20T22:51:12Z

Add a reporter replacement that assigns the correct source name and line number to a system message, as recorded in a ViewList. [1] http://mid.gmane.org/CAKMK7uFMQ2wOp99t-8v06Om78mi9OvRZWuQsFJD55QA20BB3iw@mail.gmail.com Signed-off-by: Markus Heiser Tested-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet

Documentation/sphinx: add support for specifying extra export files

2016-06-10T13:46:55Z

Let the user specify file patterns where to look for the EXPORT_SYMBOLs in addition to the file with kernel-doc comments. This is directly based on the -export-file FILE option added to kernel-doc in "kernel-doc: add support for specifying extra files for EXPORT_SYMBOLs", but we extend that with globbing patterns in the Sphinx extension. The file patterns are added as options to the :export: and :internal: arguments of the kernel-doc directive. For example, to extract the documentation of exported functions from include/net/mac80211.h: .. kernel-doc:: include/net/mac80211.h :export: net/mac80211/*.c Without the file pattern, no exported functions would be found, as the EXPORT_SYMBOLs are placed in the various source files under net/mac80211. The matched files are also added as dependencies on the document in Sphinx, as they may affect the output. This is one of the reasons to do the globbing in the Sphinx extension instead of in scripts/kernel-doc. The file pattern remains optional, and is not needed if the kernel-doc comments and EXPORT_SYMBOLs are placed in the source file passed in as the main argument to the kernel-doc directive. This is the most common case across the kernel source tree. Signed-off-by: Jani Nikula

Documentation/sphinx: use a more sensible string split in kernel-doc extension

2016-06-10T08:29:21Z

Using the default str.split doesn't return empty strings like the current version does. Signed-off-by: Jani Nikula

Documentation/sphinx: remove unnecessary temporary variable

2016-06-10T08:29:20Z

Leftover cruft. No functional changes. Signed-off-by: Jani Nikula

doc/sphinx: Track line-number of starting blocks

2016-06-04T08:35:59Z

Design is pretty simple: kernel-doc inserts breadcrumbs with line numbers, and sphinx picks them up. At first I went with a sphinx comment, but inserting those at random places seriously upsets the parser, and must be filtered. Hence why this version now uses "#define LINEO " since one of these ever escape into output it's pretty clear there is a bug. It seems to work well, and at least the 2-3 errors where sphinx complained about something that was not correct in kernel-doc text the line numbers matched up perfectly. v2: Instead of noodling around in the parser state machine, create a ViewList and parse it ourselves. This seems to be the recommended way, per Jani's suggestion. v3: - Split out ViewList pach. Splitting the kernel-doc changes from the sphinx ones isn't possible, since emitting the LINENO lines wreaks havoc with the rst formatting. We must filter them. - Improve the regex per Jani's suggestions, and compile it just once for speed. - Now that LINENO lines are eaten, also add them to function parameter descriptions. Much less content and offset than for in-line struct member descriptions, but still nice to know which exact continuation line upsets sphinx. - Simplify/clarify the line +/-1 business a bit. v4: Split out the scripts/kernel-doc changes and make line-numbers opt-in, as suggested by Jani. Cc: Jani Nikula Cc: linux-doc@vger.kernel.org Cc: Jonathan Corbet Signed-off-by: Daniel Vetter Signed-off-by: Jani Nikula

doc/sphinx: Stop touching state_machine internals

2016-06-03T08:31:37Z

Instead of just forcefully inserting our kernel-doc input and letting the state machine stumble over it the recommended way is to create ViewList, parse that and then return the list of parsed nodes. Suggested by Jani. Cc: Jani Nikula Cc: linux-doc@vger.kernel.org Cc: Jonathan Corbet Signed-off-by: Daniel Vetter Signed-off-by: Jani Nikula

doc/sphinx: Pass right filename as source

2016-06-01T09:28:31Z

With this error output becomes almost readable. The line numbers are still totally bonghits, but that's a lot harder to pull out of kerneldoc. We'd essentially have to insert some special markers in the kernel-doc output, split the output along these markers and then insert each block separately using state_machine.insert_input(block, source, first_line) Cc: Jani Nikula Cc: linux-doc@vger.kernel.org Cc: Jonathan Corbet Signed-off-by: Daniel Vetter Signed-off-by: Jani Nikula

Documentation/sphinx: fix kernel-doc extension on python3

2016-06-01T08:06:58Z

Reconcile differences between python2 and python3 on dealing with stdout, stderr from Popen. This fixes "name 'unicode' is not defined" errors on python3. We'll need to try to keep the extension working on both python-sphinx and python3-sphinx so we don't need two copies. Reported-and-tested-by: Marius Vlad Signed-off-by: Jani Nikula

Documentation/sphinx: add Sphinx kernel-doc directive extension

2016-05-30T10:38:52Z

Add an extension to handle kernel-doc directives, to call kernel-doc according to the arguments and parameters given to the reStructuredText directive. The syntax for the kernel-doc directive is: .. kernel-doc:: FILENAME :export: :internal: :functions: FUNCTION [FUNCTION ...] :doc: SECTION TITLE Of the directive options export, internal, functions, and doc, currently only one option may be given at a time. The FILENAME is relative from the kernel source tree root. The extension notifies Sphinx about the document dependency on FILENAME, causing the document to be rebuilt when the file has been changed. Signed-off-by: Jani Nikula