linux/Documentation/Makefile

216 lines
7.8 KiB
Makefile
Raw Permalink Normal View History

# -*- makefile -*-
# Makefile for Sphinx documentation
#
# for cleaning
subdir- := devicetree/bindings
# Check for broken documentation file references
ifeq ($(CONFIG_WARN_MISSING_DOCUMENTS),y)
$(shell $(srctree)/scripts/documentation-file-ref-check --warn)
endif
# Check for broken ABI files
ifeq ($(CONFIG_WARN_ABI_ERRORS),y)
$(shell $(srctree)/scripts/get_abi.pl validate --dir $(srctree)/Documentation/ABI)
endif
# You can set these variables from the command line.
SPHINXBUILD = sphinx-build
SPHINXOPTS =
SPHINXDIRS = .
DOCS_THEME =
DOCS_CSS =
_SPHINXDIRS = $(sort $(patsubst $(srctree)/Documentation/%/index.rst,%,$(wildcard $(srctree)/Documentation/*/index.rst)))
SPHINX_CONF = conf.py
PAPER =
BUILDDIR = $(obj)/output
PDFLATEX = xelatex
LATEXOPTS = -interaction=batchmode -no-shell-escape
docs: Detect variable fonts and suggest denylisting them Fedora and openSUSE has started deploying "variable font" [1] format Noto CJK fonts [2, 3]. "CJK" here stands for "Chinese, Japanese, and Korean". Unfortunately, XeTeX/XeLaTeX doesn't understand those fonts for historical reasons and builds of translations.pdf end up in errors if such fonts are present on the build host. To help developers work around the issue, add a script to check the presence of "variable font" Noto CJK fonts and to emit suggestions. The script is invoked in the error path of "make pdfdocs" so that the suggestions are made only when a PDF build actually fails. The first suggestion is to denylist those "variable font" files by activating a per-user and command-local fontconfig setting. For further info and backgrounds, please refer to the header comment of scripts/check-variable-font.sh newly added in this commit. Link: [1] https://en.wikipedia.org/wiki/Variable_font Link: [2] https://fedoraproject.org/wiki/Changes/Noto_CJK_Variable_Fonts Link: [3] https://build.opensuse.org/request/show/1157217 Reported-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/8734tqsrt7.fsf@meer.lwn.net/ Reported-by: Иван Иванович <relect@bk.ru> Link: https://lore.kernel.org/linux-doc/1708585803.600323099@f111.i.mail.ru/ Cc: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20240406020416.25096-1-akiyks@gmail.com
2024-04-06 02:04:16 +00:00
# For denylisting "variable font" files
# Can be overridden by setting as an env variable
FONTS_CONF_DENY_VF ?= $(HOME)/deny-vf
ifeq ($(findstring 1, $(KBUILD_VERBOSE)),)
SPHINXOPTS += "-q"
endif
# User-friendly check for sphinx-build
HAVE_SPHINX := $(shell if which $(SPHINXBUILD) >/dev/null 2>&1; then echo 1; else echo 0; fi)
ifeq ($(HAVE_SPHINX),0)
.DEFAULT:
$(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.)
@echo
@$(srctree)/scripts/sphinx-pre-install
@echo " SKIP Sphinx $@ target."
else # HAVE_SPHINX
# User-friendly check for pdflatex and latexmk
HAVE_PDFLATEX := $(shell if which $(PDFLATEX) >/dev/null 2>&1; then echo 1; else echo 0; fi)
HAVE_LATEXMK := $(shell if which latexmk >/dev/null 2>&1; then echo 1; else echo 0; fi)
ifeq ($(HAVE_LATEXMK),1)
PDFLATEX := latexmk -$(PDFLATEX)
endif #HAVE_LATEXMK
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
KERNELDOC = $(srctree)/scripts/kernel-doc
KERNELDOC_CONF = -D kerneldoc_srctree=$(srctree) -D kerneldoc_bin=$(KERNELDOC)
ALLSPHINXOPTS = $(KERNELDOC_CONF) $(PAPEROPT_$(PAPER)) $(SPHINXOPTS)
ifneq ($(wildcard $(srctree)/.config),)
ifeq ($(CONFIG_RUST),y)
# Let Sphinx know we will include rustdoc
ALLSPHINXOPTS += -t rustdoc
endif
endif
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
# commands; the 'cmd' from scripts/Kbuild.include is not *loopable*
loop_cmd = $(echo-cmd) $(cmd_$(1)) || exit;
# $2 sphinx builder e.g. "html"
# $3 name of the build subfolder / e.g. "userspace-api/media", used as:
# * dest folder relative to $(BUILDDIR) and
# * cache folder relative to $(BUILDDIR)/.doctrees
# $4 dest subfolder e.g. "man" for man pages at userspace-api/media/man
# $5 reST source folder relative to $(src),
# e.g. "userspace-api/media" for the linux-tv book-set at ./Documentation/userspace-api/media
quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4)
cmd_sphinx = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/userspace-api/media $2 && \
PYTHONDONTWRITEBYTECODE=1 \
BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(src)/$5/$(SPHINX_CONF)) \
$(PYTHON3) $(srctree)/scripts/jobserver-exec \
$(CONFIG_SHELL) $(srctree)/Documentation/sphinx/parallel-wrapper.sh \
$(SPHINXBUILD) \
-b $2 \
-c $(abspath $(src)) \
-d $(abspath $(BUILDDIR)/.doctrees/$3) \
-D version=$(KERNELVERSION) -D release=$(KERNELRELEASE) \
$(ALLSPHINXOPTS) \
$(abspath $(src)/$5) \
$(abspath $(BUILDDIR)/$3/$4) && \
if [ "x$(DOCS_CSS)" != "x" ]; then \
cp $(if $(patsubst /%,,$(DOCS_CSS)),$(abspath $(srctree)/$(DOCS_CSS)),$(DOCS_CSS)) $(BUILDDIR)/$3/_static/; \
fi
YNL_INDEX:=$(srctree)/Documentation/networking/netlink_spec/index.rst
YNL_RST_DIR:=$(srctree)/Documentation/networking/netlink_spec
YNL_YAML_DIR:=$(srctree)/Documentation/netlink/specs
YNL_TOOL:=$(srctree)/tools/net/ynl/ynl-gen-rst.py
YNL_RST_FILES_TMP := $(patsubst %.yaml,%.rst,$(wildcard $(YNL_YAML_DIR)/*.yaml))
YNL_RST_FILES := $(patsubst $(YNL_YAML_DIR)%,$(YNL_RST_DIR)%, $(YNL_RST_FILES_TMP))
$(YNL_INDEX): $(YNL_RST_FILES)
$(Q)$(YNL_TOOL) -o $@ -x
$(YNL_RST_DIR)/%.rst: $(YNL_YAML_DIR)/%.yaml $(YNL_TOOL)
$(Q)$(YNL_TOOL) -i $< -o $@
docs: Makefile: Add dependency to $(YNL_INDEX) for targets other than htmldocs Commit f061c9f7d058 ("Documentation: Document each netlink family") added recipes for YAML -> RST conversion. Then commit 7da8bdbf8f5d ("docs: Makefile: Fix make cleandocs by deleting generated .rst files") made sure those converted .rst files are cleaned by "make cleandocs". However, they took care of htmldocs build only. If one of other targets such as latexdocs or epubdocs is built without building htmldocs, missing .rst files can cause additional WARNINGs from sphinx-build as follow: ./Documentation/userspace-api/netlink/specs.rst:18: WARNING: undefined label: 'specs' ./Documentation/userspace-api/netlink/netlink-raw.rst:64: WARNING: unknown document: '../../networking/netlink_spec/rt_link' ./Documentation/userspace-api/netlink/netlink-raw.rst:64: WARNING: unknown document: '../../networking/netlink_spec/tc' ./Documentation/userspace-api/netlink/index.rst:21: WARNING: undefined label: 'specs' Add dependency to $(YNL_INDEX) for other targets and allow any targets to be built cleanly right after "make cleandocs". Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Cc: stable@vger.kernel.org # v6.7 Cc: Thorsten Blum <thorsten.blum@toblux.com> Cc: Breno Leitao <leitao@debian.org> Cc: Jakub Kicinski <kuba@kernel.org> Cc: "David S. Miller" <davem@davemloft.net> Reviwed-by: Breno Leitao <leitao@debian.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <e876e3c8-109d-4bc8-9916-05a4bc4ee9ac@gmail.com>
2024-03-05 04:23:00 +00:00
htmldocs texinfodocs latexdocs epubdocs xmldocs: $(YNL_INDEX)
htmldocs:
@$(srctree)/scripts/sphinx-pre-install --version-check
@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var)))
# If Rust support is available and .config exists, add rustdoc generated contents.
# If there are any, the errors from this make rustdoc will be displayed but
# won't stop the execution of htmldocs
ifneq ($(wildcard $(srctree)/.config),)
ifeq ($(CONFIG_RUST),y)
$(Q)$(MAKE) rustdoc || true
endif
endif
texinfodocs:
@$(srctree)/scripts/sphinx-pre-install --version-check
@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,texinfo,$(var),texinfo,$(var)))
# Note: the 'info' Make target is generated by sphinx itself when
# running the texinfodocs target define above.
infodocs: texinfodocs
$(MAKE) -C $(BUILDDIR)/texinfo info
linkcheckdocs:
@$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,linkcheck,$(var),,$(var)))
latexdocs:
@$(srctree)/scripts/sphinx-pre-install --version-check
@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,latex,$(var),latex,$(var)))
ifeq ($(HAVE_PDFLATEX),0)
pdfdocs:
$(warning The '$(PDFLATEX)' command was not found. Make sure you have it installed and in PATH to produce PDF output.)
@echo " SKIP Sphinx $@ target."
else # HAVE_PDFLATEX
docs: Detect variable fonts and suggest denylisting them Fedora and openSUSE has started deploying "variable font" [1] format Noto CJK fonts [2, 3]. "CJK" here stands for "Chinese, Japanese, and Korean". Unfortunately, XeTeX/XeLaTeX doesn't understand those fonts for historical reasons and builds of translations.pdf end up in errors if such fonts are present on the build host. To help developers work around the issue, add a script to check the presence of "variable font" Noto CJK fonts and to emit suggestions. The script is invoked in the error path of "make pdfdocs" so that the suggestions are made only when a PDF build actually fails. The first suggestion is to denylist those "variable font" files by activating a per-user and command-local fontconfig setting. For further info and backgrounds, please refer to the header comment of scripts/check-variable-font.sh newly added in this commit. Link: [1] https://en.wikipedia.org/wiki/Variable_font Link: [2] https://fedoraproject.org/wiki/Changes/Noto_CJK_Variable_Fonts Link: [3] https://build.opensuse.org/request/show/1157217 Reported-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/8734tqsrt7.fsf@meer.lwn.net/ Reported-by: Иван Иванович <relect@bk.ru> Link: https://lore.kernel.org/linux-doc/1708585803.600323099@f111.i.mail.ru/ Cc: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20240406020416.25096-1-akiyks@gmail.com
2024-04-06 02:04:16 +00:00
pdfdocs: DENY_VF = XDG_CONFIG_HOME=$(FONTS_CONF_DENY_VF)
pdfdocs: latexdocs
@$(srctree)/scripts/sphinx-pre-install --version-check
$(foreach var,$(SPHINXDIRS), \
docs: Detect variable fonts and suggest denylisting them Fedora and openSUSE has started deploying "variable font" [1] format Noto CJK fonts [2, 3]. "CJK" here stands for "Chinese, Japanese, and Korean". Unfortunately, XeTeX/XeLaTeX doesn't understand those fonts for historical reasons and builds of translations.pdf end up in errors if such fonts are present on the build host. To help developers work around the issue, add a script to check the presence of "variable font" Noto CJK fonts and to emit suggestions. The script is invoked in the error path of "make pdfdocs" so that the suggestions are made only when a PDF build actually fails. The first suggestion is to denylist those "variable font" files by activating a per-user and command-local fontconfig setting. For further info and backgrounds, please refer to the header comment of scripts/check-variable-font.sh newly added in this commit. Link: [1] https://en.wikipedia.org/wiki/Variable_font Link: [2] https://fedoraproject.org/wiki/Changes/Noto_CJK_Variable_Fonts Link: [3] https://build.opensuse.org/request/show/1157217 Reported-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/8734tqsrt7.fsf@meer.lwn.net/ Reported-by: Иван Иванович <relect@bk.ru> Link: https://lore.kernel.org/linux-doc/1708585803.600323099@f111.i.mail.ru/ Cc: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20240406020416.25096-1-akiyks@gmail.com
2024-04-06 02:04:16 +00:00
$(MAKE) PDFLATEX="$(PDFLATEX)" LATEXOPTS="$(LATEXOPTS)" $(DENY_VF) -C $(BUILDDIR)/$(var)/latex || sh $(srctree)/scripts/check-variable-fonts.sh || exit; \
mkdir -p $(BUILDDIR)/$(var)/pdf; \
mv $(subst .tex,.pdf,$(wildcard $(BUILDDIR)/$(var)/latex/*.tex)) $(BUILDDIR)/$(var)/pdf/; \
)
endif # HAVE_PDFLATEX
epubdocs:
@$(srctree)/scripts/sphinx-pre-install --version-check
@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,epub,$(var),epub,$(var)))
xmldocs:
@$(srctree)/scripts/sphinx-pre-install --version-check
@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,xml,$(var),xml,$(var)))
endif # HAVE_SPHINX
# The following targets are independent of HAVE_SPHINX, and the rules should
# work or silently pass without Sphinx.
refcheckdocs:
$(Q)cd $(srctree);scripts/documentation-file-ref-check
cleandocs:
$(Q)rm -f $(YNL_INDEX) $(YNL_RST_FILES)
$(Q)rm -rf $(BUILDDIR)
$(Q)$(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/userspace-api/media clean
dochelp:
@echo ' Linux kernel internal documentation in different formats from ReST:'
@echo ' htmldocs - HTML'
@echo ' texinfodocs - Texinfo'
@echo ' infodocs - Info'
@echo ' latexdocs - LaTeX'
@echo ' pdfdocs - PDF'
@echo ' epubdocs - EPUB'
@echo ' xmldocs - XML'
@echo ' linkcheckdocs - check for broken external links'
@echo ' (will connect to external hosts)'
@echo ' refcheckdocs - check for references to non-existing files under'
@echo ' Documentation'
@echo ' cleandocs - clean all generated files'
@echo
@echo ' make SPHINXDIRS="s1 s2" [target] Generate only docs of folder s1, s2'
@echo ' valid values for SPHINXDIRS are: $(_SPHINXDIRS)'
@echo
@echo ' make SPHINX_CONF={conf-file} [target] use *additional* sphinx-build'
@echo ' configuration. This is e.g. useful to build with nit-picking config.'
@echo
@echo ' make DOCS_THEME={sphinx-theme} selects a different Sphinx theme.'
@echo
@echo ' make DOCS_CSS={a .css file} adds a DOCS_CSS override file for html/epub output.'
@echo
@echo ' Default location for the generated documents is Documentation/output'