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

doc-rst: generic way to build only sphinx sub-folders 



Add a generic way to build only a reST sub-folder with or
without a individual *build-theme*.

* control *sub-folders* by environment SPHINXDIRS
* control *build-theme* by environment SPHINX_CONF

Folders with a conf.py file, matching $(srctree)/Documentation/*/conf.py
can be build and distributed *stand-alone*. E.g. to compile only the
html of 'media' and 'gpu' folder use::

  make SPHINXDIRS="media gpu" htmldocs

To use an additional sphinx-build configuration (*build-theme*) set the
name of the configuration file to SPHINX_CONF. E.g. to compile only the
html of 'media' with the *nit-picking* build use::

  make SPHINXDIRS=media SPHINX_CONF=conf_nitpick.py htmldocs

With this, the Documentation/conf.py is read first and updated with the
configuration values from the Documentation/media/conf_nitpick.py.

Signed-off-by: default avatarMarkus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent 3eb6cd68

Documentation/DocBook/Makefile

+7 −0
Original line number Original line Diff line number Diff line
@@ -22,9 +22,15 @@ ifeq ($(DOCBOOKS),) 
# Skip DocBook build if the user explicitly requested no DOCBOOKS.

# Skip DocBook build if the user explicitly requested no DOCBOOKS.

.DEFAULT:

.DEFAULT:

	@echo "  SKIP    DocBook $@ target (DOCBOOKS=\"\" specified)."

	@echo "  SKIP    DocBook $@ target (DOCBOOKS=\"\" specified)."

else

ifneq ($(SPHINXDIRS),)





# Skip DocBook build if the user explicitly requested a sphinx dir

.DEFAULT:

	@echo "  SKIP    DocBook $@ target (SPHINXDIRS specified)."

else

else







###

###

# The build process is as follows (targets):

# The build process is as follows (targets):

#              (xmldocs) [by docproc]

#              (xmldocs) [by docproc]
@@ -221,6 +227,7 @@ silent_gen_xml = : 
	   echo "</programlisting>")  > $@

	   echo "</programlisting>")  > $@





endif # DOCBOOKS=""

endif # DOCBOOKS=""

endif # SPHINDIR=...





###

###

# Help targets as used by the top-level makefile

# Help targets as used by the top-level makefile

Documentation/Makefile.sphinx

+36 −7
Original line number Original line Diff line number Diff line
@@ -5,6 +5,9 @@ 
# You can set these variables from the command line.

# You can set these variables from the command line.

SPHINXBUILD   = sphinx-build

SPHINXBUILD   = sphinx-build

SPHINXOPTS    =

SPHINXOPTS    =

SPHINXDIRS    = .

_SPHINXDIRS   = $(patsubst $(srctree)/Documentation/%/conf.py,%,$(wildcard $(srctree)/Documentation/*/conf.py))

SPHINX_CONF   = conf.py

PAPER         =

PAPER         =

BUILDDIR      = $(obj)/output

BUILDDIR      = $(obj)/output
@@ -33,30 +36,50 @@ PAPEROPT_a4 = -D latex_paper_size=a4 
PAPEROPT_letter = -D latex_paper_size=letter

PAPEROPT_letter = -D latex_paper_size=letter

KERNELDOC       = $(srctree)/scripts/kernel-doc

KERNELDOC       = $(srctree)/scripts/kernel-doc

KERNELDOC_CONF  = -D kerneldoc_srctree=$(srctree) -D kerneldoc_bin=$(KERNELDOC)

KERNELDOC_CONF  = -D kerneldoc_srctree=$(srctree) -D kerneldoc_bin=$(KERNELDOC)

ALLSPHINXOPTS   = -D version=$(KERNELVERSION) -D release=$(KERNELRELEASE) -d $(BUILDDIR)/.doctrees $(KERNELDOC_CONF) $(PAPEROPT_$(PAPER)) -c $(srctree)/$(src) $(SPHINXOPTS) $(srctree)/$(src)

ALLSPHINXOPTS   =  $(KERNELDOC_CONF) $(PAPEROPT_$(PAPER)) $(SPHINXOPTS)

# the i18n builder cannot share the environment and doctrees with the others

# the i18n builder cannot share the environment and doctrees with the others

I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .

I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .





quiet_cmd_sphinx = SPHINX  $@

# commands; the 'cmd' from scripts/Kbuild.include is not *loopable*

      cmd_sphinx = $(MAKE) BUILDDIR=$(BUILDDIR) $(build)=Documentation/media all; BUILDDIR=$(BUILDDIR) $(SPHINXBUILD) -b $2 $(ALLSPHINXOPTS) $(BUILDDIR)/$2

loop_cmd = $(echo-cmd) $(cmd_$(1))



# $2 sphinx builder e.g. "html"

# $3 name of the build subfolder / e.g. "media", used as:

#    * dest folder relative to $(BUILDDIR) and

#    * cache folder relative to $(BUILDDIR)/.doctrees

# $4 dest subfolder e.g. "man" for man pages at media/man

# $5 reST source folder relative to $(srctree)/$(src),

#    e.g. "media" for the linux-tv book-set at ./Documentation/media



quiet_cmd_sphinx = SPHINX  $@ --> file://$(abspath $(BUILDDIR)/$3/$4);

      cmd_sphinx = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/media all;\

	BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(srctree)/$(src)/$5/$(SPHINX_CONF)) \

	$(SPHINXBUILD) \

	-b $2 \

	-c $(abspath $(srctree)/$(src)) \

	-d $(abspath $(BUILDDIR)/.doctrees/$3) \

	-D version=$(KERNELVERSION) -D release=$(KERNELRELEASE) \

	$(ALLSPHINXOPTS) \

	$(abspath $(srctree)/$(src)/$5) \

	$(abspath $(BUILDDIR)/$3/$4);





htmldocs:

htmldocs:

	$(call cmd,sphinx,html)

	@$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var)))





pdfdocs:

pdfdocs:

ifeq ($(HAVE_PDFLATEX),0)

ifeq ($(HAVE_PDFLATEX),0)

	$(warning The 'pdflatex' command was not found. Make sure you have it installed and in PATH to produce PDF output.)

	$(warning The 'pdflatex' command was not found. Make sure you have it installed and in PATH to produce PDF output.)

	@echo "  SKIP    Sphinx $@ target."

	@echo "  SKIP    Sphinx $@ target."

else # HAVE_PDFLATEX

else # HAVE_PDFLATEX

	$(call cmd,sphinx,latex)

	@$(call loop_cmd,sphinx,latex,.,latex,.))

	$(Q)$(MAKE) -C $(BUILDDIR)/latex

	$(Q)$(MAKE) -C $(BUILDDIR)/latex

endif # HAVE_PDFLATEX

endif # HAVE_PDFLATEX





epubdocs:

epubdocs:

	$(call cmd,sphinx,epub)

	@$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,epub,$(var),epub,$(var)))





xmldocs:

xmldocs:

	$(call cmd,sphinx,xml)

	@$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,xml,$(var),xml,$(var)))





# no-ops for the Sphinx toolchain

# no-ops for the Sphinx toolchain

sgmldocs:

sgmldocs:
@@ -76,3 +99,9 @@ dochelp: 
	@echo  '  epubdocs        - EPUB'

	@echo  '  epubdocs        - EPUB'

	@echo  '  xmldocs         - XML'

	@echo  '  xmldocs         - XML'

	@echo  '  cleandocs       - clean all generated files'

	@echo  '  cleandocs       - clean all generated files'

	@echo

	@echo  '  make SPHINXDIRS="s1 s2" [target] Generate only docs of folder s1, s2'

	@echo  '  valid values for SPHINXDIRS are: $(_SPHINXDIRS)'

	@echo

	@echo  '  make SPHINX_CONF={conf-file} [target] use *additional* sphinx-build'

	@echo  '  configuration. This is e.g. useful to build with nit-picking config.'

Documentation/conf.py

+7 −0
Original line number Original line Diff line number Diff line
@@ -19,6 +19,7 @@ import os 
# add these directories to sys.path here. If the directory is relative to the

# 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.

# documentation root, use os.path.abspath to make it absolute, like shown here.

sys.path.insert(0, os.path.abspath('sphinx'))

sys.path.insert(0, os.path.abspath('sphinx'))

from load_config import loadConfig





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

# -- General configuration ------------------------------------------------
@@ -421,3 +422,9 @@ pdf_documents = [ 
# line arguments.

# line arguments.

kerneldoc_bin = '../scripts/kernel-doc'

kerneldoc_bin = '../scripts/kernel-doc'

kerneldoc_srctree = '..'

kerneldoc_srctree = '..'



# ------------------------------------------------------------------------------

# Since loadConfig overwrites settings from the global namespace, it has to be

# the last statement in the conf.py file

# ------------------------------------------------------------------------------

loadConfig(globals())

Documentation/sphinx/load_config.py

0 → 100644
+32 −0
Original line number Original line Diff line number Diff line 
# -*- coding: utf-8; mode: python -*-

# pylint: disable=R0903, C0330, R0914, R0912, E0401



import os

import sys

from sphinx.util.pycompat import execfile_



# ------------------------------------------------------------------------------

def loadConfig(namespace):

# ------------------------------------------------------------------------------



    u"""Load an additional configuration file into *namespace*.



    The name of the configuration file is taken from the environment

    ``SPHINX_CONF``. The external configuration file extends (or overwrites) the

    configuration values from the origin ``conf.py``.  With this you are able to

    maintain *build themes*.  """



    config_file = os.environ.get("SPHINX_CONF", None)

    if (config_file is not None

        and os.path.normpath(namespace["__file__"]) != os.path.normpath(config_file) ):

        config_file = os.path.abspath(config_file)



        if os.path.isfile(config_file):

            sys.stdout.write("load additional sphinx-config: %s\n" % config_file)

            config = namespace.copy()

            config['__file__'] = config_file

            execfile_(config_file, config)

            del config['__file__']

            namespace.update(config)

        else:

            sys.stderr.write("WARNING: additional sphinx-config not found: %s\n" % config_file)

CRA Git | Maintained and supported by SUSTech CRA and CCSE