Commit 24dcdeb2 authored by Jani Nikula's avatar Jani Nikula
Browse files

Documentation/sphinx: configure the kernel-doc extension 



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: default avatarJani Nikula <jani.nikula@intel.com>
parent c56de1db

Documentation/Makefile.sphinx

+3 −1
Original line number Diff line number Diff line
@@ -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) .

Documentation/conf.py

+8 −2
Original line number Diff line number Diff line
@@ -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:
@@ -385,3 +385,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 = '..'

CRA Git | Maintained and supported by SUSTech CRA and CCSE