Mauro Carvalho Chehab | cb43fb5 | 2017-05-14 11:50:01 -0300 | [diff] [blame] | 1 | # -*- makefile -*- |
| 2 | # Makefile for Sphinx documentation |
| 3 | # |
| 4 | |
Masahiro Yamada | a1af8d7 | 2020-02-27 02:53:25 +0900 | [diff] [blame] | 5 | # for cleaning |
| 6 | subdir- := devicetree/bindings |
Mauro Carvalho Chehab | cb43fb5 | 2017-05-14 11:50:01 -0300 | [diff] [blame] | 7 | |
Mauro Carvalho Chehab | b1663d7 | 2019-06-04 09:26:27 -0300 | [diff] [blame] | 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 | |
Mauro Carvalho Chehab | 75442fb | 2020-10-30 08:40:45 +0100 | [diff] [blame] | 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 | |
Mauro Carvalho Chehab | cb43fb5 | 2017-05-14 11:50:01 -0300 | [diff] [blame] | 18 | # You can set these variables from the command line. |
| 19 | SPHINXBUILD = sphinx-build |
| 20 | SPHINXOPTS = |
| 21 | SPHINXDIRS = . |
Mauro Carvalho Chehab | fca7216 | 2021-12-07 10:52:59 +0100 | [diff] [blame] | 22 | DOCS_THEME = |
Mauro Carvalho Chehab | 135707d | 2021-12-07 10:53:00 +0100 | [diff] [blame] | 23 | DOCS_CSS = |
Randy Dunlap | 965fc39 | 2020-02-15 23:26:06 -0800 | [diff] [blame] | 24 | _SPHINXDIRS = $(sort $(patsubst $(srctree)/Documentation/%/index.rst,%,$(wildcard $(srctree)/Documentation/*/index.rst))) |
Mauro Carvalho Chehab | cb43fb5 | 2017-05-14 11:50:01 -0300 | [diff] [blame] | 25 | SPHINX_CONF = conf.py |
| 26 | PAPER = |
| 27 | BUILDDIR = $(obj)/output |
| 28 | PDFLATEX = xelatex |
Akira Yokosawa | 6b22ce0 | 2022-02-10 10:26:53 +0900 | [diff] [blame] | 29 | LATEXOPTS = -interaction=batchmode -no-shell-escape |
Mauro Carvalho Chehab | cb43fb5 | 2017-05-14 11:50:01 -0300 | [diff] [blame] | 30 | |
Masahiro Yamada | c0d3b83 | 2022-12-23 01:25:33 +0900 | [diff] [blame] | 31 | ifeq ($(findstring 1, $(KBUILD_VERBOSE)),) |
Mauro Carvalho Chehab | d94df02 | 2020-10-27 11:56:15 +0100 | [diff] [blame] | 32 | SPHINXOPTS += "-q" |
| 33 | endif |
| 34 | |
Mauro Carvalho Chehab | cb43fb5 | 2017-05-14 11:50:01 -0300 | [diff] [blame] | 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.) |
Mauro Carvalho Chehab | 92a037f | 2017-07-16 19:08:06 -0300 | [diff] [blame] | 42 | @echo |
Jonathan Corbet | 6c01edd | 2019-05-31 10:02:11 -0600 | [diff] [blame] | 43 | @$(srctree)/scripts/sphinx-pre-install |
Mauro Carvalho Chehab | cb43fb5 | 2017-05-14 11:50:01 -0300 | [diff] [blame] | 44 | @echo " SKIP Sphinx $@ target." |
| 45 | |
| 46 | else # HAVE_SPHINX |
| 47 | |
Mauro Carvalho Chehab | 28f7c99 | 2019-03-30 10:45:58 -0300 | [diff] [blame] | 48 | # User-friendly check for pdflatex and latexmk |
Mauro Carvalho Chehab | cb43fb5 | 2017-05-14 11:50:01 -0300 | [diff] [blame] | 49 | HAVE_PDFLATEX := $(shell if which $(PDFLATEX) >/dev/null 2>&1; then echo 1; else echo 0; fi) |
Mauro Carvalho Chehab | 28f7c99 | 2019-03-30 10:45:58 -0300 | [diff] [blame] | 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 |
Mauro Carvalho Chehab | cb43fb5 | 2017-05-14 11:50:01 -0300 | [diff] [blame] | 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) |
| 62 | # the i18n builder cannot share the environment and doctrees with the others |
| 63 | I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . |
| 64 | |
| 65 | # commands; the 'cmd' from scripts/Kbuild.include is not *loopable* |
| 66 | loop_cmd = $(echo-cmd) $(cmd_$(1)) || exit; |
| 67 | |
| 68 | # $2 sphinx builder e.g. "html" |
Mauro Carvalho Chehab | 54f38fc | 2020-03-04 10:21:39 +0100 | [diff] [blame] | 69 | # $3 name of the build subfolder / e.g. "userspace-api/media", used as: |
Mauro Carvalho Chehab | cb43fb5 | 2017-05-14 11:50:01 -0300 | [diff] [blame] | 70 | # * dest folder relative to $(BUILDDIR) and |
| 71 | # * cache folder relative to $(BUILDDIR)/.doctrees |
Mauro Carvalho Chehab | 54f38fc | 2020-03-04 10:21:39 +0100 | [diff] [blame] | 72 | # $4 dest subfolder e.g. "man" for man pages at userspace-api/media/man |
Mauro Carvalho Chehab | cb43fb5 | 2017-05-14 11:50:01 -0300 | [diff] [blame] | 73 | # $5 reST source folder relative to $(srctree)/$(src), |
Mauro Carvalho Chehab | 54f38fc | 2020-03-04 10:21:39 +0100 | [diff] [blame] | 74 | # e.g. "userspace-api/media" for the linux-tv book-set at ./Documentation/userspace-api/media |
Mauro Carvalho Chehab | cb43fb5 | 2017-05-14 11:50:01 -0300 | [diff] [blame] | 75 | |
| 76 | quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4) |
Mauro Carvalho Chehab | 54f38fc | 2020-03-04 10:21:39 +0100 | [diff] [blame] | 77 | cmd_sphinx = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/userspace-api/media $2 && \ |
Mauro Carvalho Chehab | cb43fb5 | 2017-05-14 11:50:01 -0300 | [diff] [blame] | 78 | PYTHONDONTWRITEBYTECODE=1 \ |
| 79 | BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(srctree)/$(src)/$5/$(SPHINX_CONF)) \ |
Masahiro Yamada | d8d2d38 | 2021-02-01 10:00:24 +0900 | [diff] [blame] | 80 | $(PYTHON3) $(srctree)/scripts/jobserver-exec \ |
Kees Cook | 222a28e | 2021-06-17 15:58:08 -0700 | [diff] [blame] | 81 | $(CONFIG_SHELL) $(srctree)/Documentation/sphinx/parallel-wrapper.sh \ |
Mauro Carvalho Chehab | cb43fb5 | 2017-05-14 11:50:01 -0300 | [diff] [blame] | 82 | $(SPHINXBUILD) \ |
| 83 | -b $2 \ |
| 84 | -c $(abspath $(srctree)/$(src)) \ |
| 85 | -d $(abspath $(BUILDDIR)/.doctrees/$3) \ |
| 86 | -D version=$(KERNELVERSION) -D release=$(KERNELRELEASE) \ |
| 87 | $(ALLSPHINXOPTS) \ |
| 88 | $(abspath $(srctree)/$(src)/$5) \ |
Mauro Carvalho Chehab | 135707d | 2021-12-07 10:53:00 +0100 | [diff] [blame] | 89 | $(abspath $(BUILDDIR)/$3/$4) && \ |
| 90 | if [ "x$(DOCS_CSS)" != "x" ]; then \ |
Mauro Carvalho Chehab | 98d614b | 2021-12-11 09:56:59 +0100 | [diff] [blame] | 91 | cp $(if $(patsubst /%,,$(DOCS_CSS)),$(abspath $(srctree)/$(DOCS_CSS)),$(DOCS_CSS)) $(BUILDDIR)/$3/_static/; \ |
Mauro Carvalho Chehab | 135707d | 2021-12-07 10:53:00 +0100 | [diff] [blame] | 92 | fi |
Mauro Carvalho Chehab | cb43fb5 | 2017-05-14 11:50:01 -0300 | [diff] [blame] | 93 | |
| 94 | htmldocs: |
Jonathan Corbet | 18e1572 | 2019-06-04 07:55:49 -0600 | [diff] [blame] | 95 | @$(srctree)/scripts/sphinx-pre-install --version-check |
Mauro Carvalho Chehab | cb43fb5 | 2017-05-14 11:50:01 -0300 | [diff] [blame] | 96 | @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var))) |
| 97 | |
Maxim Cournoyer | 1f050e9 | 2022-11-16 14:02:09 -0500 | [diff] [blame] | 98 | texinfodocs: |
| 99 | @$(srctree)/scripts/sphinx-pre-install --version-check |
| 100 | @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,texinfo,$(var),texinfo,$(var))) |
| 101 | |
| 102 | # Note: the 'info' Make target is generated by sphinx itself when |
| 103 | # running the texinfodocs target define above. |
| 104 | infodocs: texinfodocs |
| 105 | $(MAKE) -C $(BUILDDIR)/texinfo info |
| 106 | |
Mauro Carvalho Chehab | cb43fb5 | 2017-05-14 11:50:01 -0300 | [diff] [blame] | 107 | linkcheckdocs: |
| 108 | @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,linkcheck,$(var),,$(var))) |
| 109 | |
| 110 | latexdocs: |
Jonathan Corbet | 18e1572 | 2019-06-04 07:55:49 -0600 | [diff] [blame] | 111 | @$(srctree)/scripts/sphinx-pre-install --version-check |
Mauro Carvalho Chehab | cb43fb5 | 2017-05-14 11:50:01 -0300 | [diff] [blame] | 112 | @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,latex,$(var),latex,$(var))) |
| 113 | |
| 114 | ifeq ($(HAVE_PDFLATEX),0) |
| 115 | |
| 116 | pdfdocs: |
| 117 | $(warning The '$(PDFLATEX)' command was not found. Make sure you have it installed and in PATH to produce PDF output.) |
| 118 | @echo " SKIP Sphinx $@ target." |
| 119 | |
| 120 | else # HAVE_PDFLATEX |
| 121 | |
| 122 | pdfdocs: latexdocs |
Jonathan Corbet | 18e1572 | 2019-06-04 07:55:49 -0600 | [diff] [blame] | 123 | @$(srctree)/scripts/sphinx-pre-install --version-check |
Mauro Carvalho Chehab | baeb2d5 | 2020-04-14 18:48:53 +0200 | [diff] [blame] | 124 | $(foreach var,$(SPHINXDIRS), \ |
| 125 | $(MAKE) PDFLATEX="$(PDFLATEX)" LATEXOPTS="$(LATEXOPTS)" -C $(BUILDDIR)/$(var)/latex || exit; \ |
| 126 | mkdir -p $(BUILDDIR)/$(var)/pdf; \ |
| 127 | mv $(subst .tex,.pdf,$(wildcard $(BUILDDIR)/$(var)/latex/*.tex)) $(BUILDDIR)/$(var)/pdf/; \ |
| 128 | ) |
Mauro Carvalho Chehab | cb43fb5 | 2017-05-14 11:50:01 -0300 | [diff] [blame] | 129 | |
| 130 | endif # HAVE_PDFLATEX |
| 131 | |
| 132 | epubdocs: |
Jonathan Corbet | 18e1572 | 2019-06-04 07:55:49 -0600 | [diff] [blame] | 133 | @$(srctree)/scripts/sphinx-pre-install --version-check |
Mauro Carvalho Chehab | cb43fb5 | 2017-05-14 11:50:01 -0300 | [diff] [blame] | 134 | @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,epub,$(var),epub,$(var))) |
| 135 | |
| 136 | xmldocs: |
Jonathan Corbet | 18e1572 | 2019-06-04 07:55:49 -0600 | [diff] [blame] | 137 | @$(srctree)/scripts/sphinx-pre-install --version-check |
Mauro Carvalho Chehab | cb43fb5 | 2017-05-14 11:50:01 -0300 | [diff] [blame] | 138 | @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,xml,$(var),xml,$(var))) |
| 139 | |
| 140 | endif # HAVE_SPHINX |
| 141 | |
| 142 | # The following targets are independent of HAVE_SPHINX, and the rules should |
| 143 | # work or silently pass without Sphinx. |
| 144 | |
Jani Nikula | e893922 | 2017-10-09 18:26:15 +0300 | [diff] [blame] | 145 | refcheckdocs: |
| 146 | $(Q)cd $(srctree);scripts/documentation-file-ref-check |
| 147 | |
Mauro Carvalho Chehab | cb43fb5 | 2017-05-14 11:50:01 -0300 | [diff] [blame] | 148 | cleandocs: |
| 149 | $(Q)rm -rf $(BUILDDIR) |
Mauro Carvalho Chehab | 54f38fc | 2020-03-04 10:21:39 +0100 | [diff] [blame] | 150 | $(Q)$(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/userspace-api/media clean |
Mauro Carvalho Chehab | cb43fb5 | 2017-05-14 11:50:01 -0300 | [diff] [blame] | 151 | |
| 152 | dochelp: |
| 153 | @echo ' Linux kernel internal documentation in different formats from ReST:' |
| 154 | @echo ' htmldocs - HTML' |
Maxim Cournoyer | 1f050e9 | 2022-11-16 14:02:09 -0500 | [diff] [blame] | 155 | @echo ' texinfodocs - Texinfo' |
| 156 | @echo ' infodocs - Info' |
Mauro Carvalho Chehab | cb43fb5 | 2017-05-14 11:50:01 -0300 | [diff] [blame] | 157 | @echo ' latexdocs - LaTeX' |
| 158 | @echo ' pdfdocs - PDF' |
| 159 | @echo ' epubdocs - EPUB' |
| 160 | @echo ' xmldocs - XML' |
Geert Uytterhoeven | a64c044 | 2019-10-25 13:52:32 +0200 | [diff] [blame] | 161 | @echo ' linkcheckdocs - check for broken external links' |
| 162 | @echo ' (will connect to external hosts)' |
| 163 | @echo ' refcheckdocs - check for references to non-existing files under' |
| 164 | @echo ' Documentation' |
Mauro Carvalho Chehab | cb43fb5 | 2017-05-14 11:50:01 -0300 | [diff] [blame] | 165 | @echo ' cleandocs - clean all generated files' |
| 166 | @echo |
| 167 | @echo ' make SPHINXDIRS="s1 s2" [target] Generate only docs of folder s1, s2' |
| 168 | @echo ' valid values for SPHINXDIRS are: $(_SPHINXDIRS)' |
| 169 | @echo |
| 170 | @echo ' make SPHINX_CONF={conf-file} [target] use *additional* sphinx-build' |
| 171 | @echo ' configuration. This is e.g. useful to build with nit-picking config.' |
Shuah Khan | 9effc8f | 2017-10-02 17:44:18 -0600 | [diff] [blame] | 172 | @echo |
Mauro Carvalho Chehab | 0e805b1 | 2021-12-11 09:57:00 +0100 | [diff] [blame] | 173 | @echo ' make DOCS_THEME={sphinx-theme} selects a different Sphinx theme.' |
Mauro Carvalho Chehab | fca7216 | 2021-12-07 10:52:59 +0100 | [diff] [blame] | 174 | @echo |
Mauro Carvalho Chehab | 0e805b1 | 2021-12-11 09:57:00 +0100 | [diff] [blame] | 175 | @echo ' make DOCS_CSS={a .css file} adds a DOCS_CSS override file for html/epub output.' |
Mauro Carvalho Chehab | 135707d | 2021-12-07 10:53:00 +0100 | [diff] [blame] | 176 | @echo |
Shuah Khan | 9effc8f | 2017-10-02 17:44:18 -0600 | [diff] [blame] | 177 | @echo ' Default location for the generated documents is Documentation/output' |