Commit b62b9d81 authored by Markus Heiser's avatar Markus Heiser Committed by Jonathan Corbet
Browse files

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: default avatarMarkus Heiser <markus.heiser@darmarIT.de>
Tested-by: default avatarMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent 82801d06

Documentation/sphinx/kernel-doc.py

+8 −0
Original line number Diff line number Diff line
@@ -39,6 +39,8 @@ from docutils.parsers.rst import directives 
from sphinx.util.compat import Directive

from sphinx.ext.autodoc import AutodocReporter



__version__  = '1.0'



class KernelDocDirective(Directive):

    """Extract kernel-doc comments from the specified file"""

    required_argument = 1
@@ -139,3 +141,9 @@ def setup(app): 
    app.add_config_value('kerneldoc_verbosity', 1, 'env')



    app.add_directive('kernel-doc', KernelDocDirective)



    return dict(

        version = __version__,

        parallel_read_safe = True,

        parallel_write_safe = True

    )

Documentation/sphinx/kernel_include.py

+7 −0
Original line number Diff line number Diff line
@@ -39,11 +39,18 @@ from docutils.parsers.rst import directives 
from docutils.parsers.rst.directives.body import CodeBlock, NumberLines

from docutils.parsers.rst.directives.misc import Include



__version__  = '1.0'



# ==============================================================================

def setup(app):

# ==============================================================================



    app.add_directive("kernel-include", KernelInclude)

    return dict(

        version = __version__,

        parallel_read_safe = True,

        parallel_write_safe = True

    )



# ==============================================================================

class KernelInclude(Include):

Documentation/sphinx/rstFlatTable.py

100644 → 100755
+6 −0
Original line number Diff line number Diff line
@@ -73,6 +73,12 @@ def setup(app): 
    roles.register_local_role('cspan', c_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):

# ==============================================================================

CRA Git | Maintained and supported by SUSTech CRA and CCSE