Mario Six | 8fac291 | 2018-07-10 08:40:17 +0200 | [diff] [blame] | 1 | # -*- makefile -*- |
| 2 | # Makefile for Sphinx documentation |
| 3 | # |
| 4 | |
| 5 | subdir-y := |
| 6 | |
| 7 | # You can set these variables from the command line. |
| 8 | SPHINXBUILD = sphinx-build |
| 9 | SPHINXOPTS = |
| 10 | SPHINXDIRS = . |
Breno Matheus Lima | 7e3400b | 2019-06-05 18:18:30 +0000 | [diff] [blame] | 11 | _SPHINXDIRS = $(patsubst $(srctree)/doc/%/conf.py,%,$(wildcard $(srctree)/doc/*/conf.py)) |
Mario Six | 8fac291 | 2018-07-10 08:40:17 +0200 | [diff] [blame] | 12 | SPHINX_CONF = conf.py |
| 13 | PAPER = |
| 14 | BUILDDIR = $(obj)/output |
| 15 | PDFLATEX = xelatex |
| 16 | LATEXOPTS = -interaction=batchmode |
| 17 | |
| 18 | # User-friendly check for sphinx-build |
| 19 | HAVE_SPHINX := $(shell if which $(SPHINXBUILD) >/dev/null 2>&1; then echo 1; else echo 0; fi) |
| 20 | |
| 21 | ifeq ($(HAVE_SPHINX),0) |
| 22 | |
| 23 | .DEFAULT: |
| 24 | $(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.) |
| 25 | @echo |
| 26 | @./scripts/sphinx-pre-install |
| 27 | @echo " SKIP Sphinx $@ target." |
| 28 | |
| 29 | else # HAVE_SPHINX |
| 30 | |
| 31 | # User-friendly check for pdflatex |
| 32 | HAVE_PDFLATEX := $(shell if which $(PDFLATEX) >/dev/null 2>&1; then echo 1; else echo 0; fi) |
| 33 | |
| 34 | # Internal variables. |
| 35 | PAPEROPT_a4 = -D latex_paper_size=a4 |
| 36 | PAPEROPT_letter = -D latex_paper_size=letter |
| 37 | KERNELDOC = $(srctree)/scripts/kernel-doc |
| 38 | KERNELDOC_CONF = -D kerneldoc_srctree=$(srctree) -D kerneldoc_bin=$(KERNELDOC) |
| 39 | ALLSPHINXOPTS = $(KERNELDOC_CONF) $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) |
| 40 | # the i18n builder cannot share the environment and doctrees with the others |
| 41 | I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . |
| 42 | |
| 43 | # commands; the 'cmd' from scripts/Kbuild.include is not *loopable* |
| 44 | loop_cmd = $(echo-cmd) $(cmd_$(1)) || exit; |
| 45 | |
| 46 | # $2 sphinx builder e.g. "html" |
| 47 | # $3 name of the build subfolder / e.g. "media", used as: |
| 48 | # * dest folder relative to $(BUILDDIR) and |
| 49 | # * cache folder relative to $(BUILDDIR)/.doctrees |
| 50 | # $4 dest subfolder e.g. "man" for man pages at media/man |
| 51 | # $5 reST source folder relative to $(srctree)/$(src), |
Breno Matheus Lima | 7e3400b | 2019-06-05 18:18:30 +0000 | [diff] [blame] | 52 | # e.g. "media" for the linux-tv book-set at ./doc/media |
Mario Six | 8fac291 | 2018-07-10 08:40:17 +0200 | [diff] [blame] | 53 | |
| 54 | quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4) |
Breno Matheus Lima | 7e3400b | 2019-06-05 18:18:30 +0000 | [diff] [blame] | 55 | cmd_sphinx = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=doc/media $2 && \ |
Mario Six | 8fac291 | 2018-07-10 08:40:17 +0200 | [diff] [blame] | 56 | PYTHONDONTWRITEBYTECODE=1 \ |
| 57 | BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(srctree)/$(src)/$5/$(SPHINX_CONF)) \ |
| 58 | $(SPHINXBUILD) \ |
Heinrich Schuchardt | f4993df | 2020-02-21 18:24:03 +0100 | [diff] [blame] | 59 | -W \ |
Mario Six | 8fac291 | 2018-07-10 08:40:17 +0200 | [diff] [blame] | 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 | linkcheckdocs: |
| 72 | @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,linkcheck,$(var),,$(var))) |
| 73 | |
| 74 | latexdocs: |
| 75 | @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,latex,$(var),latex,$(var))) |
| 76 | |
| 77 | ifeq ($(HAVE_PDFLATEX),0) |
| 78 | |
| 79 | pdfdocs: |
| 80 | $(warning The '$(PDFLATEX)' command was not found. Make sure you have it installed and in PATH to produce PDF output.) |
| 81 | @echo " SKIP Sphinx $@ target." |
| 82 | |
| 83 | else # HAVE_PDFLATEX |
| 84 | |
| 85 | pdfdocs: latexdocs |
| 86 | $(foreach var,$(SPHINXDIRS), $(MAKE) PDFLATEX=$(PDFLATEX) LATEXOPTS="$(LATEXOPTS)" -C $(BUILDDIR)/$(var)/latex || exit;) |
| 87 | |
| 88 | endif # HAVE_PDFLATEX |
| 89 | |
| 90 | epubdocs: |
| 91 | @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,epub,$(var),epub,$(var))) |
| 92 | |
| 93 | xmldocs: |
| 94 | @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,xml,$(var),xml,$(var))) |
| 95 | |
| 96 | endif # HAVE_SPHINX |
| 97 | |
| 98 | # The following targets are independent of HAVE_SPHINX, and the rules should |
| 99 | # work or silently pass without Sphinx. |
| 100 | |
| 101 | refcheckdocs: |
| 102 | $(Q)cd $(srctree);scripts/documentation-file-ref-check |
| 103 | |
| 104 | cleandocs: |
| 105 | $(Q)rm -rf $(BUILDDIR) |
Breno Matheus Lima | 7e3400b | 2019-06-05 18:18:30 +0000 | [diff] [blame] | 106 | $(Q)$(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=doc/media clean |
Mario Six | 8fac291 | 2018-07-10 08:40:17 +0200 | [diff] [blame] | 107 | |
| 108 | dochelp: |
Patrick Delaunay | b5c3856 | 2021-01-14 12:04:04 +0100 | [diff] [blame] | 109 | @echo ' U-Boot documentation in different formats from ReST:' |
Mario Six | 8fac291 | 2018-07-10 08:40:17 +0200 | [diff] [blame] | 110 | @echo ' htmldocs - HTML' |
| 111 | @echo ' latexdocs - LaTeX' |
| 112 | @echo ' pdfdocs - PDF' |
| 113 | @echo ' epubdocs - EPUB' |
| 114 | @echo ' xmldocs - XML' |
| 115 | @echo ' linkcheckdocs - check for broken external links (will connect to external hosts)' |
| 116 | @echo ' refcheckdocs - check for references to non-existing files under Documentation' |
| 117 | @echo ' cleandocs - clean all generated files' |
| 118 | @echo |
| 119 | @echo ' make SPHINXDIRS="s1 s2" [target] Generate only docs of folder s1, s2' |
| 120 | @echo ' valid values for SPHINXDIRS are: $(_SPHINXDIRS)' |
| 121 | @echo |
| 122 | @echo ' make SPHINX_CONF={conf-file} [target] use *additional* sphinx-build' |
| 123 | @echo ' configuration. This is e.g. useful to build with nit-picking config.' |
| 124 | @echo |
Breno Matheus Lima | 7e3400b | 2019-06-05 18:18:30 +0000 | [diff] [blame] | 125 | @echo ' Default location for the generated documents is doc/output' |