linux-kernel - [PATCH v2 06/38] Documentation/sphinx: configure the kernel-doc extension

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-Id: <24dcdeb28b55afafa9cdf6acedd78cf1aa8f8428.1465031816.git.jani.nikula@intel.com>
Date:	Sat,  4 Jun 2016 14:37:07 +0300
From:	Jani Nikula <jani.nikula@...el.com>
To:	Jonathan Corbet <corbet@....net>
Cc:	Jani Nikula <jani.nikula@...el.com>,
	Markus Heiser <markus.heiser@...marit.de>,
	Daniel Vetter <daniel.vetter@...ll.ch>,
	Grant Likely <grant.likely@...retlab.ca>,
	Mauro Carvalho Chehab <mchehab@....samsung.com>,
	Keith Packard <keithp@...thp.com>,
	LKML <linux-kernel@...r.kernel.org>, linux-doc@...r.kernel.org,
	Hans Verkuil <hverkuil@...all.nl>
Subject: [PATCH v2 06/38] 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: Jani Nikula <jani.nikula@...el.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 0f0e20757bb1..8b72577f38f5 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:
@@ -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 = '..'
-- 
2.1.4