About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / Makefile.sphinx


Based on kernel version 4.10.8. Page generated on 2017-04-01 14:43 EST.

1	# -*- makefile -*-
2	# Makefile for Sphinx documentation
3	#
4	
5	# You can set these variables from the command line.
6	SPHINXBUILD   = sphinx-build
7	SPHINXOPTS    =
8	SPHINXDIRS    = .
9	_SPHINXDIRS   = $(patsubst $(srctree)/Documentation/%/conf.py,%,$(wildcard $(srctree)/Documentation/*/conf.py))
10	SPHINX_CONF   = conf.py
11	PAPER         =
12	BUILDDIR      = $(obj)/output
13	PDFLATEX      = xelatex
14	LATEXOPTS     = -interaction=batchmode
15	
16	# User-friendly check for sphinx-build
17	HAVE_SPHINX := $(shell if which $(SPHINXBUILD) >/dev/null 2>&1; then echo 1; else echo 0; fi)
18	
19	ifeq ($(HAVE_SPHINX),0)
20	
21	.DEFAULT:
22		$(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.)
23		@echo "  SKIP    Sphinx $@ target."
24	
25	else ifneq ($(DOCBOOKS),)
26	
27	# Skip Sphinx build if the user explicitly requested DOCBOOKS.
28	.DEFAULT:
29		@echo "  SKIP    Sphinx $@ target (DOCBOOKS specified)."
30	
31	else # HAVE_SPHINX
32	
33	# User-friendly check for pdflatex
34	HAVE_PDFLATEX := $(shell if which $(PDFLATEX) >/dev/null 2>&1; then echo 1; else echo 0; fi)
35	
36	# Internal variables.
37	PAPEROPT_a4     = -D latex_paper_size=a4
38	PAPEROPT_letter = -D latex_paper_size=letter
39	KERNELDOC       = $(srctree)/scripts/kernel-doc
40	KERNELDOC_CONF  = -D kerneldoc_srctree=$(srctree) -D kerneldoc_bin=$(KERNELDOC)
41	ALLSPHINXOPTS   =  $(KERNELDOC_CONF) $(PAPEROPT_$(PAPER)) $(SPHINXOPTS)
42	# the i18n builder cannot share the environment and doctrees with the others
43	I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
44	
45	# commands; the 'cmd' from scripts/Kbuild.include is not *loopable*
46	loop_cmd = $(echo-cmd) $(cmd_$(1))
47	
48	# $2 sphinx builder e.g. "html"
49	# $3 name of the build subfolder / e.g. "media", used as:
50	#    * dest folder relative to $(BUILDDIR) and
51	#    * cache folder relative to $(BUILDDIR)/.doctrees
52	# $4 dest subfolder e.g. "man" for man pages at media/man
53	# $5 reST source folder relative to $(srctree)/$(src),
54	#    e.g. "media" for the linux-tv book-set at ./Documentation/media
55	
56	quiet_cmd_sphinx = SPHINX  $@ --> file://$(abspath $(BUILDDIR)/$3/$4)
57	      cmd_sphinx = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/media $2;\
58		BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(srctree)/$(src)/$5/$(SPHINX_CONF)) \
59		$(SPHINXBUILD) \
60		-b $2 \
61		-c $(abspath $(srctree)/$(src)) \
62		-d $(abspath $(BUILDDIR)/.doctrees/$3) \
63		-D version=$(KERNELVERSION) -D release=$(KERNELRELEASE) \
64		$(ALLSPHINXOPTS) \
65		$(abspath $(srctree)/$(src)/$5) \
66		$(abspath $(BUILDDIR)/$3/$4);
67	
68	htmldocs:
69		@$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var)))
70	
71	latexdocs:
72		@$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,latex,$(var),latex,$(var)))
73	
74	ifeq ($(HAVE_PDFLATEX),0)
75	
76	pdfdocs:
77		$(warning The '$(PDFLATEX)' command was not found. Make sure you have it installed and in PATH to produce PDF output.)
78		@echo "  SKIP    Sphinx $@ target."
79	
80	else # HAVE_PDFLATEX
81	
82	pdfdocs: latexdocs
83		$(foreach var,$(SPHINXDIRS), $(MAKE) PDFLATEX=$(PDFLATEX) LATEXOPTS="$(LATEXOPTS)" -C $(BUILDDIR)/$(var)/latex;)
84	
85	endif # HAVE_PDFLATEX
86	
87	epubdocs:
88		@$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,epub,$(var),epub,$(var)))
89	
90	xmldocs:
91		@$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,xml,$(var),xml,$(var)))
92	
93	# no-ops for the Sphinx toolchain
94	sgmldocs:
95	psdocs:
96	mandocs:
97	installmandocs:
98	
99	cleandocs:
100		$(Q)rm -rf $(BUILDDIR)
101		$(Q)$(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) -C Documentation/media clean
102	
103	endif # HAVE_SPHINX
104	
105	dochelp:
106		@echo  ' Linux kernel internal documentation in different formats (Sphinx):'
107		@echo  '  htmldocs        - HTML'
108		@echo  '  latexdocs       - LaTeX'
109		@echo  '  pdfdocs         - PDF'
110		@echo  '  epubdocs        - EPUB'
111		@echo  '  xmldocs         - XML'
112		@echo  '  cleandocs       - clean all generated files'
113		@echo
114		@echo  '  make SPHINXDIRS="s1 s2" [target] Generate only docs of folder s1, s2'
115		@echo  '  valid values for SPHINXDIRS are: $(_SPHINXDIRS)'
116		@echo
117		@echo  '  make SPHINX_CONF={conf-file} [target] use *additional* sphinx-build'
118		@echo  '  configuration. This is e.g. useful to build with nit-picking config.'
Hide Line Numbers


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog