docs: sphinx-extensions: add metadata parallel-safe

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 <markus.heiser@darmarIT.de>
Tested-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This commit is contained in:
Markus Heiser 2016-08-24 15:35:24 +02:00 committed by Jonathan Corbet
parent 82801d065b
commit b62b9d81a0
3 changed files with 21 additions and 0 deletions

View File

@ -39,6 +39,8 @@ from docutils.parsers.rst import directives
from sphinx.util.compat import Directive from sphinx.util.compat import Directive
from sphinx.ext.autodoc import AutodocReporter from sphinx.ext.autodoc import AutodocReporter
__version__ = '1.0'
class KernelDocDirective(Directive): class KernelDocDirective(Directive):
"""Extract kernel-doc comments from the specified file""" """Extract kernel-doc comments from the specified file"""
required_argument = 1 required_argument = 1
@ -139,3 +141,9 @@ def setup(app):
app.add_config_value('kerneldoc_verbosity', 1, 'env') app.add_config_value('kerneldoc_verbosity', 1, 'env')
app.add_directive('kernel-doc', KernelDocDirective) app.add_directive('kernel-doc', KernelDocDirective)
return dict(
version = __version__,
parallel_read_safe = True,
parallel_write_safe = True
)

View File

@ -39,11 +39,18 @@ from docutils.parsers.rst import directives
from docutils.parsers.rst.directives.body import CodeBlock, NumberLines from docutils.parsers.rst.directives.body import CodeBlock, NumberLines
from docutils.parsers.rst.directives.misc import Include from docutils.parsers.rst.directives.misc import Include
__version__ = '1.0'
# ============================================================================== # ==============================================================================
def setup(app): def setup(app):
# ============================================================================== # ==============================================================================
app.add_directive("kernel-include", KernelInclude) app.add_directive("kernel-include", KernelInclude)
return dict(
version = __version__,
parallel_read_safe = True,
parallel_write_safe = True
)
# ============================================================================== # ==============================================================================
class KernelInclude(Include): class KernelInclude(Include):

6
Documentation/sphinx/rstFlatTable.py Normal file → Executable file
View File

@ -73,6 +73,12 @@ def setup(app):
roles.register_local_role('cspan', c_span) roles.register_local_role('cspan', c_span)
roles.register_local_role('rspan', r_span) roles.register_local_role('rspan', r_span)
return dict(
version = __version__,
parallel_read_safe = True,
parallel_write_safe = True
)
# ============================================================================== # ==============================================================================
def c_span(name, rawtext, text, lineno, inliner, options=None, content=None): def c_span(name, rawtext, text, lineno, inliner, options=None, content=None):
# ============================================================================== # ==============================================================================