Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.kernel > #1404442

[PATCH 06/10] Documentation/sphinx: configure the kernel-doc extension

Show all headers | View raw

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

Back to linux.kernel | Previous | Next — Previous in thread | Next in thread | Find similar | Unroll thread

Thread

[PATCH 00/10] Documentation/Sphinx Jani Nikula <jani.nikula@intel.com> - 2016-05-20 15:50 +0200
  [PATCH 08/10] Documentation: add kernel hacking rst Jani Nikula <jani.nikula@intel.com> - 2016-05-20 15:50 +0200
  [PATCH 03/10] Documentation/sphinx: add basic working Sphinx configuration and build Jani Nikula <jani.nikula@intel.com> - 2016-05-20 15:50 +0200
  [PATCH 09/10] Documentation: add kernel api rst Jani Nikula <jani.nikula@intel.com> - 2016-05-20 15:50 +0200
  [PATCH 04/10] Documentation: add .gitignore Jani Nikula <jani.nikula@intel.com> - 2016-05-20 15:50 +0200
  [PATCH 02/10] kernel-doc: support printing exported and non-exported symbols Jani Nikula <jani.nikula@intel.com> - 2016-05-20 15:50 +0200
  [PATCH 05/10] Documentation/sphinx: add Sphinx kernel-doc directive extension Jani Nikula <jani.nikula@intel.com> - 2016-05-20 15:50 +0200
  [PATCH 06/10] Documentation/sphinx: configure the kernel-doc extension Jani Nikula <jani.nikula@intel.com> - 2016-05-20 15:50 +0200
  [PATCH 07/10] sphinx: cheesy script to convert .tmpl files Jani Nikula <jani.nikula@intel.com> - 2016-05-20 15:50 +0200
  [PATCH 01/10] kernel-doc: fix use of uninitialized value Jani Nikula <jani.nikula@intel.com> - 2016-05-20 15:50 +0200
  Re: [PATCH 00/10] Documentation/Sphinx Jani Nikula <jani.nikula@intel.com> - 2016-05-29 22:40 +0200
    Re: [PATCH 00/10] Documentation/Sphinx Daniel Vetter <daniel.vetter@ffwll.ch> - 2016-05-30 11:20 +0200
      Re: [PATCH 00/10] Documentation/Sphinx Markus Heiser <markus.heiser@darmarit.de> - 2016-05-30 12:50 +0200
        Re: [PATCH 00/10] Documentation/Sphinx Jani Nikula <jani.nikula@intel.com> - 2016-05-30 16:50 +0200
          Re: [PATCH 00/10] Documentation/Sphinx Daniel Vetter <daniel.vetter@ffwll.ch> - 2016-05-30 17:30 +0200
          Re: [PATCH 00/10] Documentation/Sphinx Markus Heiser <markus.heiser@darmarit.de> - 2016-05-30 18:50 +0200
            Re: [PATCH 00/10] Documentation/Sphinx Jani Nikula <jani.nikula@intel.com> - 2016-05-30 22:10 +0200
              Re: [PATCH 00/10] Documentation/Sphinx Mauro Carvalho Chehab <mchehab@osg.samsung.com> - 2016-05-30 23:30 +0200
              Re: [PATCH 00/10] Documentation/Sphinx Markus Heiser <markus.heiser@darmarit.de> - 2016-05-31 09:30 +0200
                Re: [PATCH 00/10] Documentation/Sphinx Daniel Vetter <daniel.vetter@ffwll.ch> - 2016-05-31 10:10 +0200

csiph-web