UbiquitousOS
/
OpenCloudOS-Kernel
mirror of https://gitee.com/OpenCloudOS/OpenCloudOS-Kernel.git
11
0
Fork 0
Code Issues Projects Releases Wiki Activity
OpenCloudOS-Kernel/Documentation/Makefile.sphinx

131 lines
4.4 KiB
Makefile
Raw Normal View History

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 20:14:05 +08:00
# -*- makefile -*-
# Makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXBUILD = sphinx-build
SPHINXOPTS =
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: Markus Heiser <markus.heiser@darmarIT.de> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-08-13 22:12:42 +08:00
SPHINXDIRS = .
_SPHINXDIRS = $(patsubst $(srctree)/Documentation/%/conf.py,%,$(wildcard $(srctree)/Documentation/*/conf.py))
SPHINX_CONF = conf.py
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 20:14:05 +08:00
PAPER =
BUILDDIR = $(obj)/output
Documentation/sphinx: let the user specify PDFLATEX and LATEXOPTS Refer to xelatex and latex options via variables. This allows the user to override the pdflatex and latex options to use on the make command line for experimenting. As a side effect, this makes the makefile a bit tidier. Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-11-02 16:38:43 +08:00
PDFLATEX = xelatex
Documentation/sphinx: change pdflatex interaction mode to batchmode Radically reduce the noise on stdout. The full build logs will still be available under Documentatio/output/latex/*.log. Cc: Mauro Carvalho Chehab <mchehab@osg.samsung.com> Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Tested-by: Markus Heiser <markus.heiser@darmarIT.de> Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-11-02 19:20:15 +08:00
LATEXOPTS = -interaction=batchmode
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 20:14:05 +08:00
# 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 20:24:44 +08: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 20:14:05 +08:00
else # HAVE_SPHINX
Documentation: switch to pdflatex for pdf generation Looks like rst2pdf is not robust enough, especially for large documents. Use recursive make on the Sphinx generated makefile to convert latex to pdf. The ugly detail is that pdf is generated into Documentation/output/latex. Unfortunately, the pdflatex build generates huge amounts of build log noise, and also fails in the end. We'll fix that next. Signed-off-by: Jani Nikula <jani.nikula@intel.com> Acked-by: Markus Heiser <markus.heiser@darmarit.de> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-08-10 23:54:08 +08:00
# User-friendly check for pdflatex
Documentation/sphinx: let the user specify PDFLATEX and LATEXOPTS Refer to xelatex and latex options via variables. This allows the user to override the pdflatex and latex options to use on the make command line for experimenting. As a side effect, this makes the makefile a bit tidier. Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-11-02 16:38:43 +08:00
HAVE_PDFLATEX := $(shell if which $(PDFLATEX) >/dev/null 2>&1; then echo 1; else echo 0; fi)
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 20:14:05 +08:00
# 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 16:51:47 +08:00
KERNELDOC = $(srctree)/scripts/kernel-doc
KERNELDOC_CONF = -D kerneldoc_srctree=$(srctree) -D kerneldoc_bin=$(KERNELDOC)
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: Markus Heiser <markus.heiser@darmarIT.de> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-08-13 22:12:42 +08:00
ALLSPHINXOPTS = $(KERNELDOC_CONF) $(PAPEROPT_$(PAPER)) $(SPHINXOPTS)
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 20:14:05 +08:00
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
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: Markus Heiser <markus.heiser@darmarIT.de> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-08-13 22:12:42 +08:00
# commands; the 'cmd' from scripts/Kbuild.include is not *loopable*
doc-rst: Break shell command sequences on failure As $(SHELL) doesn't include the -e option, any loop or other sequence needs to include explicit checks for failing commands. Fixes: 609afe6b49ef ("Documentation/sphinx: build the media intermediate ...") Fixes: 606b9ac81a63 ("doc-rst: generic way to build only sphinx sub-folders") Fixes: cd21379b1698 ("doc-rst: generic way to build PDF of sub-folders") Tested-by: Markus Heiser <markus.heiser@darmarit.de> Signed-off-by: Ben Hutchings <ben@decadent.org.uk> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-01-31 08:18:34 +08:00
loop_cmd = $(echo-cmd) $(cmd_$(1)) || exit;
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: Markus Heiser <markus.heiser@darmarIT.de> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-08-13 22:12:42 +08:00
# $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
Documentation/sphinx: remove superfluous trailing ; from quiet_cmd_sphinx With the unnecessary ; removed, the terminal URL detection also works better. Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-11-02 16:56:31 +08:00
quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4)
doc-rst: Break shell command sequences on failure As $(SHELL) doesn't include the -e option, any loop or other sequence needs to include explicit checks for failing commands. Fixes: 609afe6b49ef ("Documentation/sphinx: build the media intermediate ...") Fixes: 606b9ac81a63 ("doc-rst: generic way to build only sphinx sub-folders") Fixes: cd21379b1698 ("doc-rst: generic way to build PDF of sub-folders") Tested-by: Markus Heiser <markus.heiser@darmarit.de> Signed-off-by: Ben Hutchings <ben@decadent.org.uk> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-01-31 08:18:34 +08:00
cmd_sphinx = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/media $2 && \
Documentation/sphinx: prevent generation of .pyc files in the source tree Use PYTHONDONTWRITEBYTECODE=1 to prevent python from creating .pyc files in the source tree. Python 3.2 has a __pycache__ scheme [1], but before that the only alternative seems to be to copy the source files to the build tree to ensure the .pyc files are created there too. Just prevent .pyc file generation for simplicity. Considering the small amount of python code to compile (assuming sphinx itself has .pyc around), the impact on build is neglible. [1] http://stackoverflow.com/questions/3522079/changing-the-directory-where-pyc-files-are-created References: http://lkml.kernel.org/r/CAMuHMdVxqpH7-9XJ+YE_pgoA+-fe0969cSkOehYh3uubYcrhZA@mail.gmail.com Reported-by: Geert Uytterhoeven <geert@linux-m68k.org> References: http://lkml.kernel.org/r/1485816692.2900.17.camel@decadent.org.uk Reported-by: Ben Hutchings <ben@decadent.org.uk> Cc: Jonathan Corbet <corbet@lwn.net> Signed-off-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-02-01 02:18:05 +08:00
PYTHONDONTWRITEBYTECODE=1 \
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: Markus Heiser <markus.heiser@darmarIT.de> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-08-13 22:12:42 +08:00
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) \
doc-rst: Break shell command sequences on failure As $(SHELL) doesn't include the -e option, any loop or other sequence needs to include explicit checks for failing commands. Fixes: 609afe6b49ef ("Documentation/sphinx: build the media intermediate ...") Fixes: 606b9ac81a63 ("doc-rst: generic way to build only sphinx sub-folders") Fixes: cd21379b1698 ("doc-rst: generic way to build PDF of sub-folders") Tested-by: Markus Heiser <markus.heiser@darmarit.de> Signed-off-by: Ben Hutchings <ben@decadent.org.uk> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-01-31 08:18:34 +08:00
$(abspath $(BUILDDIR)/$3/$4)
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 20:14:05 +08:00
htmldocs:
doc-rst: Fix recursive make invocation from macros In any case where we recurse but don't mention $(MAKE) literally in the recipe, we need to add a '+' at the start of the command to ensure that parallel makes and various other options work properly. Fixes: 609afe6b49ef ("Documentation/sphinx: build the media intermediate ...") Tested-by: Markus Heiser <markus.heiser@darmarit.de> Signed-off-by: Ben Hutchings <ben@decadent.org.uk> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-01-31 08:18:56 +08:00
@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var)))
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 20:14:05 +08:00
Add a target to check broken external links in the Documentation Documentation shouldn't have broken links. sphinx linkcheck builder scans all documents for external links, tries to open them with urllib2, and writes an overview which ones are broken and redirected to standard output and to output.txt in the output directory. Reviewed-by: Jani Nikula <jani.nikula@intel.com> Tested-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Rémy Léone <remy.leone@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-02-15 20:16:35 +08:00
linkcheckdocs:
@$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,linkcheck,$(var),,$(var)))
docs-rst: add support for LaTeX output Sphinx supports LaTeX output. Sometimes, it is interesting to call it directly, instead of also generating a PDF. As it comes for free, add a target for it. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-08-18 22:53:39 +08:00
latexdocs:
doc-rst: Fix recursive make invocation from macros In any case where we recurse but don't mention $(MAKE) literally in the recipe, we need to add a '+' at the start of the command to ensure that parallel makes and various other options work properly. Fixes: 609afe6b49ef ("Documentation/sphinx: build the media intermediate ...") Tested-by: Markus Heiser <markus.heiser@darmarit.de> Signed-off-by: Ben Hutchings <ben@decadent.org.uk> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-01-31 08:18:56 +08:00
@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,latex,$(var),latex,$(var)))
Documentation/sphinx: make it possible to build latexdocs without pdflatex Building latexdocs doesn't actually require $(PDFLATEX). Move the checks for it to the pdfdocs target which does require it, and specifically outside of the target in order to not depend on latexdocs when we can't build pdfdocs anyway. Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Tested-by: Markus Heiser <markus.heiser@darmarIT.de> Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-11-02 17:13:19 +08:00
Documentation: switch to pdflatex for pdf generation Looks like rst2pdf is not robust enough, especially for large documents. Use recursive make on the Sphinx generated makefile to convert latex to pdf. The ugly detail is that pdf is generated into Documentation/output/latex. Unfortunately, the pdflatex build generates huge amounts of build log noise, and also fails in the end. We'll fix that next. Signed-off-by: Jani Nikula <jani.nikula@intel.com> Acked-by: Markus Heiser <markus.heiser@darmarit.de> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-08-10 23:54:08 +08:00
ifeq ($(HAVE_PDFLATEX),0)
Documentation/sphinx: make it possible to build latexdocs without pdflatex Building latexdocs doesn't actually require $(PDFLATEX). Move the checks for it to the pdfdocs target which does require it, and specifically outside of the target in order to not depend on latexdocs when we can't build pdfdocs anyway. Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Tested-by: Markus Heiser <markus.heiser@darmarIT.de> Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-11-02 17:13:19 +08:00
pdfdocs:
Documentation/sphinx: let the user specify PDFLATEX and LATEXOPTS Refer to xelatex and latex options via variables. This allows the user to override the pdflatex and latex options to use on the make command line for experimenting. As a side effect, this makes the makefile a bit tidier. Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-11-02 16:38:43 +08:00
$(warning The '$(PDFLATEX)' command was not found. Make sure you have it installed and in PATH to produce PDF output.)
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 20:14:05 +08:00
@echo " SKIP Sphinx $@ target."
Documentation/sphinx: make it possible to build latexdocs without pdflatex Building latexdocs doesn't actually require $(PDFLATEX). Move the checks for it to the pdfdocs target which does require it, and specifically outside of the target in order to not depend on latexdocs when we can't build pdfdocs anyway. Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Tested-by: Markus Heiser <markus.heiser@darmarIT.de> Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-11-02 17:13:19 +08:00
Documentation: switch to pdflatex for pdf generation Looks like rst2pdf is not robust enough, especially for large documents. Use recursive make on the Sphinx generated makefile to convert latex to pdf. The ugly detail is that pdf is generated into Documentation/output/latex. Unfortunately, the pdflatex build generates huge amounts of build log noise, and also fails in the end. We'll fix that next. Signed-off-by: Jani Nikula <jani.nikula@intel.com> Acked-by: Markus Heiser <markus.heiser@darmarit.de> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-08-10 23:54:08 +08:00
else # HAVE_PDFLATEX
docs-rst: add support for LaTeX output Sphinx supports LaTeX output. Sometimes, it is interesting to call it directly, instead of also generating a PDF. As it comes for free, add a target for it. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-08-18 22:53:39 +08:00
pdfdocs: latexdocs
doc-rst: Break shell command sequences on failure As $(SHELL) doesn't include the -e option, any loop or other sequence needs to include explicit checks for failing commands. Fixes: 609afe6b49ef ("Documentation/sphinx: build the media intermediate ...") Fixes: 606b9ac81a63 ("doc-rst: generic way to build only sphinx sub-folders") Fixes: cd21379b1698 ("doc-rst: generic way to build PDF of sub-folders") Tested-by: Markus Heiser <markus.heiser@darmarit.de> Signed-off-by: Ben Hutchings <ben@decadent.org.uk> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-01-31 08:18:34 +08:00
$(foreach var,$(SPHINXDIRS), $(MAKE) PDFLATEX=$(PDFLATEX) LATEXOPTS="$(LATEXOPTS)" -C $(BUILDDIR)/$(var)/latex || exit;)
Documentation/sphinx: let the user specify PDFLATEX and LATEXOPTS Refer to xelatex and latex options via variables. This allows the user to override the pdflatex and latex options to use on the make command line for experimenting. As a side effect, this makes the makefile a bit tidier. Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-11-02 16:38:43 +08:00
Documentation: switch to pdflatex for pdf generation Looks like rst2pdf is not robust enough, especially for large documents. Use recursive make on the Sphinx generated makefile to convert latex to pdf. The ugly detail is that pdf is generated into Documentation/output/latex. Unfortunately, the pdflatex build generates huge amounts of build log noise, and also fails in the end. We'll fix that next. Signed-off-by: Jani Nikula <jani.nikula@intel.com> Acked-by: Markus Heiser <markus.heiser@darmarit.de> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-08-10 23:54:08 +08:00
endif # HAVE_PDFLATEX
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 20:14:05 +08:00
epubdocs:
doc-rst: Fix recursive make invocation from macros In any case where we recurse but don't mention $(MAKE) literally in the recipe, we need to add a '+' at the start of the command to ensure that parallel makes and various other options work properly. Fixes: 609afe6b49ef ("Documentation/sphinx: build the media intermediate ...") Tested-by: Markus Heiser <markus.heiser@darmarit.de> Signed-off-by: Ben Hutchings <ben@decadent.org.uk> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-01-31 08:18:56 +08:00
@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,epub,$(var),epub,$(var)))
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 20:14:05 +08:00
xmldocs:
doc-rst: Fix recursive make invocation from macros In any case where we recurse but don't mention $(MAKE) literally in the recipe, we need to add a '+' at the start of the command to ensure that parallel makes and various other options work properly. Fixes: 609afe6b49ef ("Documentation/sphinx: build the media intermediate ...") Tested-by: Markus Heiser <markus.heiser@darmarit.de> Signed-off-by: Ben Hutchings <ben@decadent.org.uk> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-01-31 08:18:56 +08:00
@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,xml,$(var),xml,$(var)))
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 20:14:05 +08:00
Documentation/sphinx: make targets independent of Sphinx work for HAVE_SPHINX=0 Make targets that don't depend on Sphinx work without warnings about missing Sphinx. 'make cleandocs' will work without Sphinx just fine, and the targets that are no-ops for Sphinx should just be skipped. Move them outside of the HAVE_SPHINX checks to take precedence over the .DEFAULT target for HAVE_SPHINX=0. Reported-by: Jim Davis <jim.epost@gmail.com> Reference: http://lkml.kernel.org/r/CA+r1ZhjRVqkjPXGOGB_BOAX2Hkfb+qQCtTzFfBMFeH1Mfeej7w@mail.gmail.com Signed-off-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-01-31 00:58:15 +08:00
endif # HAVE_SPHINX
# The following targets are independent of HAVE_SPHINX, and the rules should
# work or silently pass without 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 20:14:05 +08:00
# no-ops for the Sphinx toolchain
sgmldocs:
Documentation: make Makefile.sphinx no-ops quieter Silence the "make[1]: Nothing to be done for ..." messages for the no-op targets in Makefile.sphinx. Signed-off-by: Jim Davis <jim.epost@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-02-11 08:06:50 +08:00
@:
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 20:14:05 +08:00
psdocs:
Documentation: make Makefile.sphinx no-ops quieter Silence the "make[1]: Nothing to be done for ..." messages for the no-op targets in Makefile.sphinx. Signed-off-by: Jim Davis <jim.epost@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-02-11 08:06:50 +08:00
@:
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 20:14:05 +08:00
mandocs:
Documentation: make Makefile.sphinx no-ops quieter Silence the "make[1]: Nothing to be done for ..." messages for the no-op targets in Makefile.sphinx. Signed-off-by: Jim Davis <jim.epost@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-02-11 08:06:50 +08:00
@:
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 20:14:05 +08:00
installmandocs:
Documentation: make Makefile.sphinx no-ops quieter Silence the "make[1]: Nothing to be done for ..." messages for the no-op targets in Makefile.sphinx. Signed-off-by: Jim Davis <jim.epost@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-02-11 08:06:50 +08:00
@:
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 20:14:05 +08:00
cleandocs:
$(Q)rm -rf $(BUILDDIR)
doc-rst: fixed cleandoc target when used with O=dir The cleandocs target won't work if I use a different output folder:: $ make O=/tmp/kernel SPHINXDIRS="process" cleandocs make[1]: Entering directory '/tmp/kernel' make[3]: *** No rule to make target 'clean'. Stop. ... Documentation/Makefile.sphinx:100: recipe for target 'cleandocs' failed Signed-off-by: Markus Heiser <markus.heiser@darmarit.de> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-01-31 17:57:41 +08:00
$(Q)$(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/media clean
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 20:14:05 +08:00
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 20:41:48 +08:00
dochelp:
@echo ' Linux kernel internal documentation in different formats (Sphinx):'
@echo ' htmldocs - HTML'
docs-rst: add support for LaTeX output Sphinx supports LaTeX output. Sometimes, it is interesting to call it directly, instead of also generating a PDF. As it comes for free, add a target for it. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-08-18 22:53:39 +08:00
@echo ' latexdocs - LaTeX'
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 20:41:48 +08:00
@echo ' pdfdocs - PDF'
@echo ' epubdocs - EPUB'
@echo ' xmldocs - XML'
Add a target to check broken external links in the Documentation Documentation shouldn't have broken links. sphinx linkcheck builder scans all documents for external links, tries to open them with urllib2, and writes an overview which ones are broken and redirected to standard output and to output.txt in the output directory. Reviewed-by: Jani Nikula <jani.nikula@intel.com> Tested-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Rémy Léone <remy.leone@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-02-15 20:16:35 +08:00
@echo ' linkcheckdocs - check for broken external links (will connect to external hosts)'
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 20:41:48 +08:00
@echo ' cleandocs - clean all generated 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: Markus Heiser <markus.heiser@darmarIT.de> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-08-13 22:12:42 +08:00
@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.'