Commit | Line | Data |
---|---|---|
cb43fb57 MCC |
1 | # -*- makefile -*- |
2 | # Makefile for Sphinx documentation | |
3 | # | |
4 | ||
a1af8d71 MY |
5 | # for cleaning |
6 | subdir- := devicetree/bindings | |
cb43fb57 | 7 | |
b1663d7e MCC |
8 | # Check for broken documentation file references |
9 | ifeq ($(CONFIG_WARN_MISSING_DOCUMENTS),y) | |
10 | $(shell $(srctree)/scripts/documentation-file-ref-check --warn) | |
11 | endif | |
12 | ||
75442fb0 MCC |
13 | # Check for broken ABI files |
14 | ifeq ($(CONFIG_WARN_ABI_ERRORS),y) | |
15 | $(shell $(srctree)/scripts/get_abi.pl validate --dir $(srctree)/Documentation/ABI) | |
16 | endif | |
17 | ||
cb43fb57 MCC |
18 | # You can set these variables from the command line. |
19 | SPHINXBUILD = sphinx-build | |
20 | SPHINXOPTS = | |
21 | SPHINXDIRS = . | |
fca7216b | 22 | DOCS_THEME = |
135707d3 | 23 | DOCS_CSS = |
965fc39f | 24 | _SPHINXDIRS = $(sort $(patsubst $(srctree)/Documentation/%/index.rst,%,$(wildcard $(srctree)/Documentation/*/index.rst))) |
cb43fb57 MCC |
25 | SPHINX_CONF = conf.py |
26 | PAPER = | |
27 | BUILDDIR = $(obj)/output | |
28 | PDFLATEX = xelatex | |
6b22ce00 | 29 | LATEXOPTS = -interaction=batchmode -no-shell-escape |
cb43fb57 | 30 | |
c0d3b831 | 31 | ifeq ($(findstring 1, $(KBUILD_VERBOSE)),) |
d94df02c MCC |
32 | SPHINXOPTS += "-q" |
33 | endif | |
34 | ||
cb43fb57 MCC |
35 | # User-friendly check for sphinx-build |
36 | HAVE_SPHINX := $(shell if which $(SPHINXBUILD) >/dev/null 2>&1; then echo 1; else echo 0; fi) | |
37 | ||
38 | ifeq ($(HAVE_SPHINX),0) | |
39 | ||
40 | .DEFAULT: | |
41 | $(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 | 42 | @echo |
6c01edd3 | 43 | @$(srctree)/scripts/sphinx-pre-install |
cb43fb57 MCC |
44 | @echo " SKIP Sphinx $@ target." |
45 | ||
46 | else # HAVE_SPHINX | |
47 | ||
28f7c994 | 48 | # User-friendly check for pdflatex and latexmk |
cb43fb57 | 49 | HAVE_PDFLATEX := $(shell if which $(PDFLATEX) >/dev/null 2>&1; then echo 1; else echo 0; fi) |
28f7c994 MCC |
50 | HAVE_LATEXMK := $(shell if which latexmk >/dev/null 2>&1; then echo 1; else echo 0; fi) |
51 | ||
52 | ifeq ($(HAVE_LATEXMK),1) | |
53 | PDFLATEX := latexmk -$(PDFLATEX) | |
54 | endif #HAVE_LATEXMK | |
cb43fb57 MCC |
55 | |
56 | # Internal variables. | |
57 | PAPEROPT_a4 = -D latex_paper_size=a4 | |
58 | PAPEROPT_letter = -D latex_paper_size=letter | |
59 | KERNELDOC = $(srctree)/scripts/kernel-doc | |
60 | KERNELDOC_CONF = -D kerneldoc_srctree=$(srctree) -D kerneldoc_bin=$(KERNELDOC) | |
61 | ALLSPHINXOPTS = $(KERNELDOC_CONF) $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) | |
c3521105 CB |
62 | ifneq ($(wildcard $(srctree)/.config),) |
63 | ifeq ($(CONFIG_RUST),y) | |
64 | # Let Sphinx know we will include rustdoc | |
65 | ALLSPHINXOPTS += -t rustdoc | |
66 | endif | |
67 | endif | |
cb43fb57 MCC |
68 | # the i18n builder cannot share the environment and doctrees with the others |
69 | I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . | |
70 | ||
71 | # commands; the 'cmd' from scripts/Kbuild.include is not *loopable* | |
72 | loop_cmd = $(echo-cmd) $(cmd_$(1)) || exit; | |
73 | ||
74 | # $2 sphinx builder e.g. "html" | |
54f38fca | 75 | # $3 name of the build subfolder / e.g. "userspace-api/media", used as: |
cb43fb57 MCC |
76 | # * dest folder relative to $(BUILDDIR) and |
77 | # * cache folder relative to $(BUILDDIR)/.doctrees | |
54f38fca | 78 | # $4 dest subfolder e.g. "man" for man pages at userspace-api/media/man |
cb43fb57 | 79 | # $5 reST source folder relative to $(srctree)/$(src), |
54f38fca | 80 | # e.g. "userspace-api/media" for the linux-tv book-set at ./Documentation/userspace-api/media |
cb43fb57 MCC |
81 | |
82 | quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4) | |
54f38fca | 83 | cmd_sphinx = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/userspace-api/media $2 && \ |
cb43fb57 MCC |
84 | PYTHONDONTWRITEBYTECODE=1 \ |
85 | BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(srctree)/$(src)/$5/$(SPHINX_CONF)) \ | |
d8d2d382 | 86 | $(PYTHON3) $(srctree)/scripts/jobserver-exec \ |
222a28ed | 87 | $(CONFIG_SHELL) $(srctree)/Documentation/sphinx/parallel-wrapper.sh \ |
cb43fb57 MCC |
88 | $(SPHINXBUILD) \ |
89 | -b $2 \ | |
90 | -c $(abspath $(srctree)/$(src)) \ | |
91 | -d $(abspath $(BUILDDIR)/.doctrees/$3) \ | |
92 | -D version=$(KERNELVERSION) -D release=$(KERNELRELEASE) \ | |
93 | $(ALLSPHINXOPTS) \ | |
94 | $(abspath $(srctree)/$(src)/$5) \ | |
135707d3 MCC |
95 | $(abspath $(BUILDDIR)/$3/$4) && \ |
96 | if [ "x$(DOCS_CSS)" != "x" ]; then \ | |
98d614bd | 97 | cp $(if $(patsubst /%,,$(DOCS_CSS)),$(abspath $(srctree)/$(DOCS_CSS)),$(DOCS_CSS)) $(BUILDDIR)/$3/_static/; \ |
135707d3 | 98 | fi |
cb43fb57 MCC |
99 | |
100 | htmldocs: | |
18e15724 | 101 | @$(srctree)/scripts/sphinx-pre-install --version-check |
cb43fb57 MCC |
102 | @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var))) |
103 | ||
c3521105 CB |
104 | # If Rust support is available and .config exists, add rustdoc generated contents. |
105 | # If there are any, the errors from this make rustdoc will be displayed but | |
106 | # won't stop the execution of htmldocs | |
107 | ||
108 | ifneq ($(wildcard $(srctree)/.config),) | |
109 | ifeq ($(CONFIG_RUST),y) | |
110 | $(Q)$(MAKE) rustdoc || true | |
111 | endif | |
112 | endif | |
113 | ||
1f050e90 MC |
114 | texinfodocs: |
115 | @$(srctree)/scripts/sphinx-pre-install --version-check | |
116 | @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,texinfo,$(var),texinfo,$(var))) | |
117 | ||
118 | # Note: the 'info' Make target is generated by sphinx itself when | |
119 | # running the texinfodocs target define above. | |
120 | infodocs: texinfodocs | |
121 | $(MAKE) -C $(BUILDDIR)/texinfo info | |
122 | ||
cb43fb57 MCC |
123 | linkcheckdocs: |
124 | @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,linkcheck,$(var),,$(var))) | |
125 | ||
126 | latexdocs: | |
18e15724 | 127 | @$(srctree)/scripts/sphinx-pre-install --version-check |
cb43fb57 MCC |
128 | @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,latex,$(var),latex,$(var))) |
129 | ||
130 | ifeq ($(HAVE_PDFLATEX),0) | |
131 | ||
132 | pdfdocs: | |
133 | $(warning The '$(PDFLATEX)' command was not found. Make sure you have it installed and in PATH to produce PDF output.) | |
134 | @echo " SKIP Sphinx $@ target." | |
135 | ||
136 | else # HAVE_PDFLATEX | |
137 | ||
138 | pdfdocs: latexdocs | |
18e15724 | 139 | @$(srctree)/scripts/sphinx-pre-install --version-check |
baeb2d5c MCC |
140 | $(foreach var,$(SPHINXDIRS), \ |
141 | $(MAKE) PDFLATEX="$(PDFLATEX)" LATEXOPTS="$(LATEXOPTS)" -C $(BUILDDIR)/$(var)/latex || exit; \ | |
142 | mkdir -p $(BUILDDIR)/$(var)/pdf; \ | |
143 | mv $(subst .tex,.pdf,$(wildcard $(BUILDDIR)/$(var)/latex/*.tex)) $(BUILDDIR)/$(var)/pdf/; \ | |
144 | ) | |
cb43fb57 MCC |
145 | |
146 | endif # HAVE_PDFLATEX | |
147 | ||
148 | epubdocs: | |
18e15724 | 149 | @$(srctree)/scripts/sphinx-pre-install --version-check |
cb43fb57 MCC |
150 | @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,epub,$(var),epub,$(var))) |
151 | ||
152 | xmldocs: | |
18e15724 | 153 | @$(srctree)/scripts/sphinx-pre-install --version-check |
cb43fb57 MCC |
154 | @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,xml,$(var),xml,$(var))) |
155 | ||
156 | endif # HAVE_SPHINX | |
157 | ||
158 | # The following targets are independent of HAVE_SPHINX, and the rules should | |
159 | # work or silently pass without Sphinx. | |
160 | ||
e8939222 JN |
161 | refcheckdocs: |
162 | $(Q)cd $(srctree);scripts/documentation-file-ref-check | |
163 | ||
cb43fb57 MCC |
164 | cleandocs: |
165 | $(Q)rm -rf $(BUILDDIR) | |
54f38fca | 166 | $(Q)$(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/userspace-api/media clean |
cb43fb57 MCC |
167 | |
168 | dochelp: | |
169 | @echo ' Linux kernel internal documentation in different formats from ReST:' | |
170 | @echo ' htmldocs - HTML' | |
1f050e90 MC |
171 | @echo ' texinfodocs - Texinfo' |
172 | @echo ' infodocs - Info' | |
cb43fb57 MCC |
173 | @echo ' latexdocs - LaTeX' |
174 | @echo ' pdfdocs - PDF' | |
175 | @echo ' epubdocs - EPUB' | |
176 | @echo ' xmldocs - XML' | |
a64c0440 GU |
177 | @echo ' linkcheckdocs - check for broken external links' |
178 | @echo ' (will connect to external hosts)' | |
179 | @echo ' refcheckdocs - check for references to non-existing files under' | |
180 | @echo ' Documentation' | |
cb43fb57 MCC |
181 | @echo ' cleandocs - clean all generated files' |
182 | @echo | |
183 | @echo ' make SPHINXDIRS="s1 s2" [target] Generate only docs of folder s1, s2' | |
184 | @echo ' valid values for SPHINXDIRS are: $(_SPHINXDIRS)' | |
185 | @echo | |
186 | @echo ' make SPHINX_CONF={conf-file} [target] use *additional* sphinx-build' | |
187 | @echo ' configuration. This is e.g. useful to build with nit-picking config.' | |
9effc8f7 | 188 | @echo |
0e805b11 | 189 | @echo ' make DOCS_THEME={sphinx-theme} selects a different Sphinx theme.' |
fca7216b | 190 | @echo |
0e805b11 | 191 | @echo ' make DOCS_CSS={a .css file} adds a DOCS_CSS override file for html/epub output.' |
135707d3 | 192 | @echo |
9effc8f7 | 193 | @echo ' Default location for the generated documents is Documentation/output' |