linux-hardened/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 ifneq ($(DOCBOOKS),)

# Skip Sphinx build if the user explicitly requested DOCBOOKS.
.DEFAULT:
	@echo "  SKIP    Sphinx $@ target (DOCBOOKS specified)."

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 = BUILDDIR=$(BUILDDIR) $(SPHINXBUILD) -b $2 $(ALLSPHINXOPTS) $(BUILDDIR)/$2

htmldocs:
	$(MAKE) BUILDDIR=$(BUILDDIR) -f $(srctree)/Documentation/media/Makefile $@
	$(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

dochelp:
	@echo  ' Linux kernel internal documentation in different formats (Sphinx):'
	@echo  '  htmldocs        - HTML'
	@echo  '  pdfdocs         - PDF'
	@echo  '  epubdocs        - EPUB'
	@echo  '  xmldocs         - XML'
	@echo  '  cleandocs       - clean all generated files'
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 14:14:05 +02: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."`

Documentation/sphinx: skip build if user requested specific DOCBOOKS If the user requested specific DocBooks to be built using 'make DOCBOOKS=foo.xml htmldocs', assume no Sphinx build is desired. This check is transitional, and can be removed once we drop the DocBook build. Cc: Markus Heiser <markus.heiser@darmarit.de> Cc: Mauro Carvalho Chehab <mchehab@osg.samsung.com> Fixes: 22cba31bae9d ("Documentation/sphinx: add basic working Sphinx configuration and build") Signed-off-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> 2016-07-01 14:24:44 +02:00			`else ifneq ($(DOCBOOKS),)`

			`# Skip Sphinx build if the user explicitly requested DOCBOOKS.`
			`.DEFAULT:`
			`@echo " SKIP Sphinx $@ target (DOCBOOKS specified)."`

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 14:14:05 +02:00			`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 10:51:47 +02: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 14:25:41 +02: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 14:14:05 +02:00			`# the i18n builder cannot share the environment and doctrees with the others`
			`I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .`

			`quiet_cmd_sphinx = SPHINX $@`
doc-rst: linux_tv/Makefile: Honor quiet make O=dir To honor the: make O=dir [targets] Locate all output files in "dir" * activate kernel-include directive * export BUILDDIR=$(BUILDDIR) * linux_tv: replace '.. include::' with '.. kernel-include:: $BUILDDIR/<foo.h.rst>' Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> 2016-07-08 14:15:05 +02:00			`cmd_sphinx = BUILDDIR=$(BUILDDIR) $(SPHINXBUILD) -b $2 $(ALLSPHINXOPTS) $(BUILDDIR)/$2`
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 14:14:05 +02:00
			`htmldocs:`
doc_rst: rename the media Sphinx suff to Documentation/media The name of the subsystem is "media", and not "linux_tv". Also, as we plan to add other stuff there in the future, let's rename also the media uAPI book to media_uapi, to make it clearer. No functional changes. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> 2016-07-08 16:40:06 +02:00			`$(MAKE) BUILDDIR=$(BUILDDIR) -f $(srctree)/Documentation/media/Makefile $@`
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 14:14:05 +02:00			`$(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)`

Documentation/sphinx: do not warn about missing tools in 'make help' Simply move the dochelp rule outside of the HAVE_SPHINX check, overriding the .DEFAULT rule for HAVE_SPHINX=0. Cc: Jonathan Corbet <corbet@lwn.net> Cc: Christian Kujau <lists@nerdbynature.de> Signed-off-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> 2016-08-01 11:37:05 +02:00			`endif # HAVE_SPHINX`

Documentation: add top level 'make help' output for Sphinx While there's slight overlap with the DocBook help now, this can stay intact when the DocBook help goes away. Signed-off-by: Jani Nikula <jani.nikula@intel.com> 2016-06-22 14:41:48 +02:00			`dochelp:`
			`@echo ' Linux kernel internal documentation in different formats (Sphinx):'`
			`@echo ' htmldocs - HTML'`
			`@echo ' pdfdocs - PDF'`
			`@echo ' epubdocs - EPUB'`
			`@echo ' xmldocs - XML'`
			`@echo ' cleandocs - clean all generated files'`