]>
Commit | Line | Data |
---|---|---|
cb43fb57 MCC |
1 | # -*- makefile -*- |
2 | # Makefile for Sphinx documentation | |
3 | # | |
4 | ||
4f0e3a57 | 5 | subdir-y := devicetree/bindings/ |
cb43fb57 | 6 | |
b1663d7e MCC |
7 | # Check for broken documentation file references |
8 | ifeq ($(CONFIG_WARN_MISSING_DOCUMENTS),y) | |
9 | $(shell $(srctree)/scripts/documentation-file-ref-check --warn) | |
10 | endif | |
11 | ||
cb43fb57 MCC |
12 | # You can set these variables from the command line. |
13 | SPHINXBUILD = sphinx-build | |
14 | SPHINXOPTS = | |
15 | SPHINXDIRS = . | |
16 | _SPHINXDIRS = $(patsubst $(srctree)/Documentation/%/conf.py,%,$(wildcard $(srctree)/Documentation/*/conf.py)) | |
17 | SPHINX_CONF = conf.py | |
18 | PAPER = | |
19 | BUILDDIR = $(obj)/output | |
20 | PDFLATEX = xelatex | |
21 | LATEXOPTS = -interaction=batchmode | |
22 | ||
23 | # User-friendly check for sphinx-build | |
24 | HAVE_SPHINX := $(shell if which $(SPHINXBUILD) >/dev/null 2>&1; then echo 1; else echo 0; fi) | |
25 | ||
26 | ifeq ($(HAVE_SPHINX),0) | |
27 | ||
28 | .DEFAULT: | |
29 | $(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.) | |
92a037f0 | 30 | @echo |
6c01edd3 | 31 | @$(srctree)/scripts/sphinx-pre-install |
cb43fb57 MCC |
32 | @echo " SKIP Sphinx $@ target." |
33 | ||
34 | else # HAVE_SPHINX | |
35 | ||
cf08508d MCC |
36 | export SPHINXOPTS = $(shell perl -e 'open IN,"sphinx-build --version 2>&1 |"; while (<IN>) { if (m/([\d\.]+)/) { print "-jauto" if ($$1 >= "1.7") } ;} close IN') |
37 | ||
28f7c994 | 38 | # User-friendly check for pdflatex and latexmk |
cb43fb57 | 39 | HAVE_PDFLATEX := $(shell if which $(PDFLATEX) >/dev/null 2>&1; then echo 1; else echo 0; fi) |
28f7c994 MCC |
40 | HAVE_LATEXMK := $(shell if which latexmk >/dev/null 2>&1; then echo 1; else echo 0; fi) |
41 | ||
42 | ifeq ($(HAVE_LATEXMK),1) | |
43 | PDFLATEX := latexmk -$(PDFLATEX) | |
44 | endif #HAVE_LATEXMK | |
cb43fb57 MCC |
45 | |
46 | # Internal variables. | |
47 | PAPEROPT_a4 = -D latex_paper_size=a4 | |
48 | PAPEROPT_letter = -D latex_paper_size=letter | |
49 | KERNELDOC = $(srctree)/scripts/kernel-doc | |
50 | KERNELDOC_CONF = -D kerneldoc_srctree=$(srctree) -D kerneldoc_bin=$(KERNELDOC) | |
51 | ALLSPHINXOPTS = $(KERNELDOC_CONF) $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) | |
52 | # the i18n builder cannot share the environment and doctrees with the others | |
53 | I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . | |
54 | ||
55 | # commands; the 'cmd' from scripts/Kbuild.include is not *loopable* | |
56 | loop_cmd = $(echo-cmd) $(cmd_$(1)) || exit; | |
57 | ||
58 | # $2 sphinx builder e.g. "html" | |
59 | # $3 name of the build subfolder / e.g. "media", used as: | |
60 | # * dest folder relative to $(BUILDDIR) and | |
61 | # * cache folder relative to $(BUILDDIR)/.doctrees | |
62 | # $4 dest subfolder e.g. "man" for man pages at media/man | |
63 | # $5 reST source folder relative to $(srctree)/$(src), | |
64 | # e.g. "media" for the linux-tv book-set at ./Documentation/media | |
65 | ||
66 | quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4) | |
67 | cmd_sphinx = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/media $2 && \ | |
68 | PYTHONDONTWRITEBYTECODE=1 \ | |
69 | BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(srctree)/$(src)/$5/$(SPHINX_CONF)) \ | |
70 | $(SPHINXBUILD) \ | |
71 | -b $2 \ | |
72 | -c $(abspath $(srctree)/$(src)) \ | |
73 | -d $(abspath $(BUILDDIR)/.doctrees/$3) \ | |
74 | -D version=$(KERNELVERSION) -D release=$(KERNELRELEASE) \ | |
75 | $(ALLSPHINXOPTS) \ | |
76 | $(abspath $(srctree)/$(src)/$5) \ | |
77 | $(abspath $(BUILDDIR)/$3/$4) | |
78 | ||
79 | htmldocs: | |
18e15724 | 80 | @$(srctree)/scripts/sphinx-pre-install --version-check |
cb43fb57 MCC |
81 | @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var))) |
82 | ||
83 | linkcheckdocs: | |
84 | @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,linkcheck,$(var),,$(var))) | |
85 | ||
86 | latexdocs: | |
18e15724 | 87 | @$(srctree)/scripts/sphinx-pre-install --version-check |
cb43fb57 MCC |
88 | @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,latex,$(var),latex,$(var))) |
89 | ||
90 | ifeq ($(HAVE_PDFLATEX),0) | |
91 | ||
92 | pdfdocs: | |
93 | $(warning The '$(PDFLATEX)' command was not found. Make sure you have it installed and in PATH to produce PDF output.) | |
94 | @echo " SKIP Sphinx $@ target." | |
95 | ||
96 | else # HAVE_PDFLATEX | |
97 | ||
98 | pdfdocs: latexdocs | |
18e15724 | 99 | @$(srctree)/scripts/sphinx-pre-install --version-check |
28f7c994 | 100 | $(foreach var,$(SPHINXDIRS), $(MAKE) PDFLATEX="$(PDFLATEX)" LATEXOPTS="$(LATEXOPTS)" -C $(BUILDDIR)/$(var)/latex || exit;) |
cb43fb57 MCC |
101 | |
102 | endif # HAVE_PDFLATEX | |
103 | ||
104 | epubdocs: | |
18e15724 | 105 | @$(srctree)/scripts/sphinx-pre-install --version-check |
cb43fb57 MCC |
106 | @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,epub,$(var),epub,$(var))) |
107 | ||
108 | xmldocs: | |
18e15724 | 109 | @$(srctree)/scripts/sphinx-pre-install --version-check |
cb43fb57 MCC |
110 | @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,xml,$(var),xml,$(var))) |
111 | ||
112 | endif # HAVE_SPHINX | |
113 | ||
114 | # The following targets are independent of HAVE_SPHINX, and the rules should | |
115 | # work or silently pass without Sphinx. | |
116 | ||
e8939222 JN |
117 | refcheckdocs: |
118 | $(Q)cd $(srctree);scripts/documentation-file-ref-check | |
119 | ||
cb43fb57 MCC |
120 | cleandocs: |
121 | $(Q)rm -rf $(BUILDDIR) | |
122 | $(Q)$(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/media clean | |
123 | ||
124 | dochelp: | |
125 | @echo ' Linux kernel internal documentation in different formats from ReST:' | |
126 | @echo ' htmldocs - HTML' | |
127 | @echo ' latexdocs - LaTeX' | |
128 | @echo ' pdfdocs - PDF' | |
129 | @echo ' epubdocs - EPUB' | |
130 | @echo ' xmldocs - XML' | |
131 | @echo ' linkcheckdocs - check for broken external links (will connect to external hosts)' | |
e8939222 | 132 | @echo ' refcheckdocs - check for references to non-existing files under Documentation' |
cb43fb57 MCC |
133 | @echo ' cleandocs - clean all generated files' |
134 | @echo | |
135 | @echo ' make SPHINXDIRS="s1 s2" [target] Generate only docs of folder s1, s2' | |
136 | @echo ' valid values for SPHINXDIRS are: $(_SPHINXDIRS)' | |
137 | @echo | |
138 | @echo ' make SPHINX_CONF={conf-file} [target] use *additional* sphinx-build' | |
139 | @echo ' configuration. This is e.g. useful to build with nit-picking config.' | |
9effc8f7 SK |
140 | @echo |
141 | @echo ' Default location for the generated documents is Documentation/output' |