linux/Documentation/Makefile.sphinx

# -*- makefile -*-
# Makefile for Sphinx documentation
#

# You can set these variables from the command line.
SPHINXBUILD   = sphinx-build
SPHINXOPTS    =
PAPER         =
BUILDDIR      = $(obj)/output

# User-friendly check for sphinx-build
HAVE_SPHINX := $(shell if which $(SPHINXBUILD) >/dev/null 2>&1; then echo 1; else echo 0; fi)

ifeq ($(HAVE_SPHINX),0)

.DEFAULT:
	$(warning The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed and in PATH, or set the SPHINXBUILD make variable to point to the full path of the '$(SPHINXBUILD)' executable.)
	@echo "  SKIP    Sphinx $@ target."

else # HAVE_SPHINX

# User-friendly check for rst2pdf
HAVE_RST2PDF := $(shell if python -c "import rst2pdf" >/dev/null 2>&1; then echo 1; else echo 0; fi)

# Internal variables.
PAPEROPT_a4     = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
KERNELDOC       = $(srctree)/scripts/kernel-doc
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)
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .

quiet_cmd_sphinx = SPHINX  $@
      cmd_sphinx = $(SPHINXBUILD) -b $2 $(ALLSPHINXOPTS) $(BUILDDIR)/$2

htmldocs:
	$(call cmd,sphinx,html)

pdfdocs:
ifeq ($(HAVE_RST2PDF),0)
	$(warning The Python 'rst2pdf' module was not found. Make sure you have the module installed to produce PDF output.)
	@echo "  SKIP    Sphinx $@ target."
else # HAVE_RST2PDF
	$(call cmd,sphinx,pdf)
endif # HAVE_RST2PDF

epubdocs:
	$(call cmd,sphinx,epub)

xmldocs:
	$(call cmd,sphinx,xml)

# no-ops for the Sphinx toolchain
sgmldocs:
psdocs:
mandocs:
installmandocs:

cleandocs:
	$(Q)rm -rf $(BUILDDIR)

endif # HAVE_SPHINX
Documentation/sphinx: add basic working Sphinx configuration and build Add basic configuration and makefile to build documentation from any .rst files under Documentation using Sphinx. For starters, there's just the placeholder index.rst. At the top level Makefile, hook Sphinx documentation targets alongside (but independent of) the DocBook toolchain, having both be run on the various 'make *docs' targets. All Sphinx processing is placed into Documentation/Makefile.sphinx. Both that and the Documentation/DocBook/Makefile are now expected to handle all the documentation targets, explicitly ignoring them if they're not relevant for that particular toolchain. The changes to the existing DocBook Makefile are kept minimal. There is graceful handling of missing Sphinx and rst2pdf (which is needed for pdf output) by checking for the tool and python module, respectively, with informative messages to the user. If the Read the Docs theme (sphinx_rtd_theme) is available, use it, but otherwise gracefully fall back to the Sphinx default theme, with an informative message to the user, and slightly less pretty HTML output. Sphinx can now handle htmldocs, pdfdocs (if rst2pdf is available), epubdocs and xmldocs targets. The output documents are written into per output type subdirectories under Documentation/output. Finally, you can pass options to sphinx-build using the SPHINXBUILD make variable. For example, 'make SPHINXOPTS=-v htmldocs' for more verbose output from Sphinx. This is based on the original work by Jonathan Corbet, but he probably wouldn't recognize this as his own anymore. Signed-off-by: Jani Nikula <jani.nikula@intel.com> 2016-05-19 12:14:05 +00:00			`# -- makefile --`
			`# Makefile for Sphinx documentation`
			`#`

			`# You can set these variables from the command line.`
			`SPHINXBUILD = sphinx-build`
			`SPHINXOPTS =`
			`PAPER =`
			`BUILDDIR = $(obj)/output`

			`# User-friendly check for sphinx-build`
			`HAVE_SPHINX := $(shell if which $(SPHINXBUILD) >/dev/null 2>&1; then echo 1; else echo 0; fi)`

			`ifeq ($(HAVE_SPHINX),0)`

			`.DEFAULT:`
			`$(warning The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed and in PATH, or set the SPHINXBUILD make variable to point to the full path of the '$(SPHINXBUILD)' executable.)`
			`@echo " SKIP Sphinx $@ target."`

			`else # HAVE_SPHINX`

			`# User-friendly check for rst2pdf`
			`HAVE_RST2PDF := $(shell if python -c "import rst2pdf" >/dev/null 2>&1; then echo 1; else echo 0; fi)`

			`# Internal variables.`
			`PAPEROPT_a4 = -D latex_paper_size=a4`
			`PAPEROPT_letter = -D latex_paper_size=letter`
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@intel.com> 2016-05-20 08:51:47 +00:00			`KERNELDOC = $(srctree)/scripts/kernel-doc`
			`KERNELDOC_CONF = -D kerneldoc_srctree=$(srctree) -D kerneldoc_bin=$(KERNELDOC)`
Documentation/sphinx: set version and release properly Read the version and release from the top level Makefile (for use when Sphinx is invoked directly, by e.g. Read the Docs), but override them via Sphinx command line arguments in a normal documentation build. Signed-off-by: Jani Nikula <jani.nikula@intel.com> 2016-05-28 12:25:41 +00:00			`ALLSPHINXOPTS = -D version=$(KERNELVERSION) -D release=$(KERNELRELEASE) -d $(BUILDDIR)/.doctrees $(KERNELDOC_CONF) $(PAPEROPT_$(PAPER)) -c $(srctree)/$(src) $(SPHINXOPTS) $(srctree)/$(src)`
Documentation/sphinx: add basic working Sphinx configuration and build Add basic configuration and makefile to build documentation from any .rst files under Documentation using Sphinx. For starters, there's just the placeholder index.rst. At the top level Makefile, hook Sphinx documentation targets alongside (but independent of) the DocBook toolchain, having both be run on the various 'make *docs' targets. All Sphinx processing is placed into Documentation/Makefile.sphinx. Both that and the Documentation/DocBook/Makefile are now expected to handle all the documentation targets, explicitly ignoring them if they're not relevant for that particular toolchain. The changes to the existing DocBook Makefile are kept minimal. There is graceful handling of missing Sphinx and rst2pdf (which is needed for pdf output) by checking for the tool and python module, respectively, with informative messages to the user. If the Read the Docs theme (sphinx_rtd_theme) is available, use it, but otherwise gracefully fall back to the Sphinx default theme, with an informative message to the user, and slightly less pretty HTML output. Sphinx can now handle htmldocs, pdfdocs (if rst2pdf is available), epubdocs and xmldocs targets. The output documents are written into per output type subdirectories under Documentation/output. Finally, you can pass options to sphinx-build using the SPHINXBUILD make variable. For example, 'make SPHINXOPTS=-v htmldocs' for more verbose output from Sphinx. This is based on the original work by Jonathan Corbet, but he probably wouldn't recognize this as his own anymore. Signed-off-by: Jani Nikula <jani.nikula@intel.com> 2016-05-19 12:14:05 +00:00			`# the i18n builder cannot share the environment and doctrees with the others`
			`I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .`

			`quiet_cmd_sphinx = SPHINX $@`
			`cmd_sphinx = $(SPHINXBUILD) -b $2 $(ALLSPHINXOPTS) $(BUILDDIR)/$2`

			`htmldocs:`
			`$(call cmd,sphinx,html)`

			`pdfdocs:`
			`ifeq ($(HAVE_RST2PDF),0)`
			`$(warning The Python 'rst2pdf' module was not found. Make sure you have the module installed to produce PDF output.)`
			`@echo " SKIP Sphinx $@ target."`
			`else # HAVE_RST2PDF`
			`$(call cmd,sphinx,pdf)`
			`endif # HAVE_RST2PDF`

			`epubdocs:`
			`$(call cmd,sphinx,epub)`

			`xmldocs:`
			`$(call cmd,sphinx,xml)`

			`# no-ops for the Sphinx toolchain`
			`sgmldocs:`
			`psdocs:`
			`mandocs:`
			`installmandocs:`

			`cleandocs:`
			`$(Q)rm -rf $(BUILDDIR)`

			`endif # HAVE_SPHINX`