projects/linux·blob master · refs

120 lines · 4.3 KiB

1# -*- makefile -*-
2# Makefile for Sphinx documentation
3#
4
5# for cleaning
6subdir- := devicetree/bindings
7
8ifneq ($(MAKECMDGOALS),cleandocs)
9# Check for broken documentation file references
10ifeq ($(CONFIG_WARN_MISSING_DOCUMENTS),y)
11$(shell $(srctree)/tools/docs/documentation-file-ref-check --warn)
12endif
13
14# Check for broken ABI files
15ifeq ($(CONFIG_WARN_ABI_ERRORS),y)
16$(shell $(srctree)/tools/docs/get_abi.py --dir $(srctree)/Documentation/ABI validate)
17endif
18endif
19
20# You can set these variables from the command line.
21SPHINXBUILD = sphinx-build
22SPHINXOPTS =
23SPHINXDIRS = .
24DOCS_THEME =
25DOCS_CSS =
26RUSTDOC =
27PAPER =
28BUILDDIR = $(obj)/output
29PDFLATEX = xelatex
30LATEXOPTS = -interaction=batchmode -no-shell-escape
31
32PYTHONPYCACHEPREFIX ?= $(abspath $(BUILDDIR)/__pycache__)
33
34# Wrapper for sphinx-build
35
36BUILD_WRAPPER = $(srctree)/tools/docs/sphinx-build-wrapper
37
38# For denylisting "variable font" files
39# Can be overridden by setting as an env variable
40FONTS_CONF_DENY_VF ?= $(HOME)/deny-vf
41
42# User-friendly check for sphinx-build
43HAVE_SPHINX := $(shell if which $(SPHINXBUILD) >/dev/null 2>&1; then echo 1; else echo 0; fi)
44
45ifeq ($(HAVE_SPHINX),0)
46
47.DEFAULT:
48 $(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.)
49 @echo
50 @$(srctree)/tools/docs/sphinx-pre-install
51 @echo " SKIP Sphinx $@ target."
52
53else # HAVE_SPHINX
54
55# Common documentation targets
56htmldocs mandocs infodocs texinfodocs latexdocs epubdocs xmldocs pdfdocs linkcheckdocs:
57 $(Q)PYTHONPYCACHEPREFIX="$(PYTHONPYCACHEPREFIX)" \
58 $(srctree)/tools/docs/sphinx-pre-install --version-check
59 +$(Q)PYTHONPYCACHEPREFIX="$(PYTHONPYCACHEPREFIX)" \
60 $(PYTHON3) $(BUILD_WRAPPER) $@ \
61 --sphinxdirs="$(SPHINXDIRS)" $(RUSTDOC) \
62 --builddir="$(BUILDDIR)" --deny-vf=$(FONTS_CONF_DENY_VF) \
63 --theme=$(DOCS_THEME) --css=$(DOCS_CSS) --paper=$(PAPER)
64
65
66endif
67
68# The following targets are independent of HAVE_SPHINX, and the rules should
69# work or silently pass without Sphinx.
70
71htmldocs-redirects: $(srctree)/Documentation/.renames.txt
72 @tools/docs/gen-redirects.py --output $(BUILDDIR) < $<
73
74refcheckdocs:
75 $(Q)cd $(srctree); tools/docs/documentation-file-ref-check
76
77testdocs:
78 $(Q)PYTHONPYCACHEPREFIX="$(PYTHONPYCACHEPREFIX)" \
79 $(PYTHON3) $(srctree)/tools/unittests/run.py
80
81cleandocs:
82 $(Q)rm -rf $(BUILDDIR)
83
84# Used only on help
85_SPHINXDIRS = $(shell printf "%s\n" $(patsubst $(srctree)/Documentation/%/index.rst,%,$(wildcard $(srctree)/Documentation/*/index.rst)) | sort -f)
86
87dochelp:
88 @echo ' Linux kernel internal documentation in different formats from ReST:'
89 @echo ' htmldocs - HTML'
90 @echo ' htmldocs-redirects - generate HTML redirects for moved pages'
91 @echo ' texinfodocs - Texinfo'
92 @echo ' infodocs - Info'
93 @echo ' mandocs - Man pages'
94 @echo ' latexdocs - LaTeX'
95 @echo ' pdfdocs - PDF'
96 @echo ' epubdocs - EPUB'
97 @echo ' xmldocs - XML'
98 @echo ' linkcheckdocs - check for broken external links'
99 @echo ' (will connect to external hosts)'
100 @echo ' refcheckdocs - check for references to non-existing files under'
101 @echo ' Documentation'
102 @echo ' testdocs - run the unit tests of the documentation tools'
103 @echo ' cleandocs - clean all generated files'
104 @echo
105 @echo ' make SPHINXDIRS="s1 s2" [target] Generate only docs of folder s1, s2'
106 @echo ' top level values for SPHINXDIRS are:'
107 @echo '$(_SPHINXDIRS)' | fmt -s -w 75 -g 75 | sed 's/^/ /'
108 @echo ' you may also use a subdirectory like SPHINXDIRS=userspace-api/media,'
109 @echo ' provided that there is an index.rst file at the subdirectory.'
110 @echo
111 @echo ' make DOCS_THEME={sphinx-theme} selects a different Sphinx theme.'
112 @echo
113 @echo ' make DOCS_CSS={a .css file} adds a DOCS_CSS override file for html/epub output.'
114 @echo
115 @echo ' make PAPER={a4|letter} Specifies the paper size used for LaTeX/PDF output.'
116 @echo
117 @echo ' make FONTS_CONF_DENY_VF={path} sets a deny list to block variable Noto CJK fonts'
118 @echo ' for PDF build. See tools/lib/python/kdoc/latex_fonts.py for more details'
119 @echo
120 @echo ' Default location for the generated documents is Documentation/output'