lkml.org 
[lkml]   [2016]   [May]   [20]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    Patch in this message
    /
    From
    Subject[PATCH 06/10] Documentation/sphinx: configure the kernel-doc extension
    Date
    Tell Sphinx where to find the extension, and pass on the kernel src tree
    and kernel-doc paths to the extension.

    With this, any .rst files under Documentation may contain the kernel-doc
    rst directive to include kernel-doc documentation from any source file.

    While building, it may be handy to pass kernel-doc extension
    configuration on the command line. For example, 'make SPHINXOPTS="-D
    kerneldoc_verbosity=0" htmldocs' silences all stderr output from
    kernel-doc when the kernel-doc exit code is 0. (The stderr will be
    logged unconditionally when the exit code is non-zero.)

    Signed-off-by: Jani Nikula <jani.nikula@intel.com>
    ---
    Documentation/Makefile.sphinx | 4 +++-
    Documentation/conf.py | 10 ++++++++--
    2 files changed, 11 insertions(+), 3 deletions(-)

    diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx
    index 25a7970bfe5c..8a662be9bd87 100644
    --- a/Documentation/Makefile.sphinx
    +++ b/Documentation/Makefile.sphinx
    @@ -25,7 +25,9 @@ HAVE_RST2PDF := $(shell if python -c "import rst2pdf" >/dev/null 2>&1; then echo
    # Internal variables.
    PAPEROPT_a4 = -D latex_paper_size=a4
    PAPEROPT_letter = -D latex_paper_size=letter
    -ALLSPHINXOPTS = -d $(BUILDDIR)/.doctrees $(PAPEROPT_$(PAPER)) -c $(srctree)/$(src) $(SPHINXOPTS) $(srctree)/$(src)
    +KERNELDOC = $(srctree)/scripts/kernel-doc
    +KERNELDOC_CONF = -D kerneldoc_srctree=$(srctree) -D kerneldoc_bin=$(KERNELDOC)
    +ALLSPHINXOPTS = -d $(BUILDDIR)/.doctrees $(KERNELDOC_CONF) $(PAPEROPT_$(PAPER)) -c $(srctree)/$(src) $(SPHINXOPTS) $(srctree)/$(src)
    # the i18n builder cannot share the environment and doctrees with the others
    I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .

    diff --git a/Documentation/conf.py b/Documentation/conf.py
    index ff86f5e88049..0d33cb157716 100644
    --- a/Documentation/conf.py
    +++ b/Documentation/conf.py
    @@ -18,7 +18,7 @@ import os
    # If extensions (or modules to document with autodoc) are in another directory,
    # add these directories to sys.path here. If the directory is relative to the
    # documentation root, use os.path.abspath to make it absolute, like shown here.
    -#sys.path.insert(0, os.path.abspath('.'))
    +sys.path.insert(0, os.path.abspath('sphinx'))

    # -- General configuration ------------------------------------------------

    @@ -28,7 +28,7 @@ import os
    # Add any Sphinx extension module names here, as strings. They can be
    # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
    # ones.
    -extensions = []
    +extensions = ['kernel-doc']

    # Gracefully handle missing rst2pdf.
    try:
    @@ -376,3 +376,9 @@ epub_exclude_files = ['search.html']
    pdf_documents = [
    ('index', u'Kernel', u'Kernel', u'J. Random Bozo'),
    ]
    +
    +# kernel-doc extension configuration for running Sphinx directly (e.g. by Read
    +# the Docs). In a normal build, these are supplied from the Makefile via command
    +# line arguments.
    +kerneldoc_bin = '../scripts/kernel-doc'
    +kerneldoc_srctree = '..'
    --
    2.1.4
    \
     
     \ /
      Last update: 2016-05-20 16:01    [W:4.016 / U:0.008 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site