Documentation Makefile

정리 대상과 사전 문서 검사

이 file은 Sphinx documentation을 build하는 Makefile입니다. `subdir- := devicetree/bindings`는 정리 대상 하위 directory를 등록합니다.

`cleandocs`가 아닌 target을 실행할 때만 broken documentation file reference와 ABI file을 검사합니다. `CONFIG_WARN_MISSING_DOCUMENTS=y`이면 `scripts/documentation-file-ref-check --warn`을 실행합니다.

`CONFIG_WARN_ABI_ERRORS=y`이면 `scripts/get_abi.py --dir Documentation/ABI validate`를 실행해 ABI file을 검증합니다. 정리 작업에서는 이런 사전 검사를 건너뜁니다.

# -*- makefile -*-
# Makefile for Sphinx documentation
#

# for cleaning
subdir- := devicetree/bindings

ifneq ($(MAKECMDGOALS),cleandocs)
# 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.py --dir $(srctree)/Documentation/ABI validate)
endif
endif

Command-line 변수와 기본값

사용자는 command line에서 Sphinx build 관련 변수를 덮어쓸 수 있습니다. `SPHINXBUILD`는 executable, `SPHINXOPTS`는 추가 option, `SPHINXDIRS`는 build할 문서 집합, `DOCS_THEME`와 `DOCS_CSS`는 theme와 CSS override입니다.

`_SPHINXDIRS`는 `Documentation/*/index.rst`를 찾아 유효한 최상위 Sphinx directory 목록을 계산합니다. `SPHINX_CONF=conf.py`, `PAPER`, `BUILDDIR=$(obj)/output`, `PDFLATEX=xelatex`, `LATEXOPTS=-interaction=batchmode -no-shell-escape`도 기본값으로 둡니다.

Variable font file을 denylist하기 위한 fontconfig 위치는 `FONTS_CONF_DENY_VF ?= $(HOME)/deny-vf`이며 environment variable로 덮어쓸 수 있습니다.

`KBUILD_VERBOSE`에 1이 없으면 `SPHINXOPTS`에 `-q`를 추가해 조용한 output을 사용합니다. 마지막으로 `which sphinx-build` 결과를 `HAVE_SPHINX`에 저장합니다.

# 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

# 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)

Sphinx가 없을 때의 동작

`HAVE_SPHINX=0`이면 `.DEFAULT` rule이 모든 Sphinx target을 대신 처리합니다.

먼저 `sphinx-build` command를 찾지 못했다는 warning과 함께 Sphinx를 설치해 `PATH`에 넣거나 `SPHINXBUILD` make variable로 전체 경로를 지정하라고 안내합니다.

그 다음 `scripts/sphinx-pre-install`을 실행해 설치 정보를 보여 주고, 요청한 Sphinx target을 `SKIP`했다고 출력합니다. Build를 이해하기 어려운 command-not-found 오류로 끝내지 않고 사용 가능한 안내를 제공합니다.

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)

PDF tool과 내부 Sphinx option

Sphinx가 있으면 `pdflatex` 역할의 `PDFLATEX` command와 `latexmk` 존재 여부를 검사합니다. `latexmk`가 있으면 `PDFLATEX`를 `latexmk -$(PDFLATEX)` 형태로 바꿔 PDF build를 관리합니다.

Paper size option은 A4와 letter용 `PAPEROPT_a4`, `PAPEROPT_letter`로 나뉩니다. `ALLSPHINXOPTS`에는 kernel source tree와 `kernel-doc` binary 위치를 정의하고 선택한 paper option과 사용자 `SPHINXOPTS`를 더합니다.

Kernel `.config`가 있고 `CONFIG_RUST=y`이면 Sphinx에 `-t rustdoc` tag를 넘겨 rustdoc 생성 내용을 포함한다고 알립니다.

i18n builder는 다른 builder와 environment·doctree를 공유할 수 없어 별도 `I18NSPHINXOPTS`를 사용합니다. `loop_cmd`는 Kbuild의 loop 불가능한 `cmd`를 여러 `SPHINXDIRS`에 적용하도록 감싼 command입니다.

ifeq ($(HAVE_LATEXMK),1)
        PDFLATEX := latexmk -$(PDFLATEX)
endif #HAVE_LATEXMK

# Internal variables.
PAPEROPT_a4     = -D latex_elements.papersize=a4paper
PAPEROPT_letter = -D latex_elements.papersize=letterpaper
ALLSPHINXOPTS   = -D kerneldoc_srctree=$(srctree) -D kerneldoc_bin=$(KERNELDOC)
ALLSPHINXOPTS   += $(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

Sphinx command와 HTML target

주석의 `$2`는 `html` 같은 Sphinx builder, `$3`는 build·doctree cache 하위 directory, `$4`는 man page 같은 destination subfolder, `$5`는 `Documentation` 기준 reST source folder입니다.

`PYTHONPYCACHEPREFIX`는 build output 아래 `__pycache__`를 사용합니다. `quiet_cmd_sphinx`는 target과 file URL을 표시하고, `cmd_sphinx`는 environment와 모든 Sphinx option을 조합해 실제 build를 실행합니다.

실행 chain은 `jobserver-exec`, `parallel-wrapper.sh`, `sphinx-build`를 거치며 builder, config, doctree cache, kernel version·release, source, destination을 전달합니다.

`DOCS_CSS`가 지정되면 상대 경로는 source tree 기준 absolute path로 바꿔 build 결과의 `_static`에 복사합니다.

`htmldocs`는 dependency version check 뒤 모든 `SPHINXDIRS`를 html builder로 build합니다. `htmldocs-redirects`는 `.renames.txt`를 입력으로 moved page redirect를 생성합니다.

Rust support와 `.config`가 있으면 `make rustdoc`을 실행하지만 오류가 html documentation build 전체를 중단하지 않도록 `|| true`를 사용합니다.

# $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

PYTHONPYCACHEPREFIX ?= $(abspath $(BUILDDIR)/__pycache__)

quiet_cmd_sphinx = SPHINX  $@ --> file://$(abspath $(BUILDDIR)/$3/$4)
      cmd_sphinx = \
        PYTHONPYCACHEPREFIX="$(PYTHONPYCACHEPREFIX)" \
        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

htmldocs:
        @$(srctree)/scripts/sphinx-pre-install --version-check
        @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var)))

htmldocs-redirects: $(srctree)/Documentation/.renames.txt
        @tools/docs/gen-redirects.py --output $(BUILDDIR) < $<

# If Rust support is available and .config exists, add rustdoc generated contents.

Texinfo·linkcheck·LaTeX·PDF target

`texinfodocs`는 version check 뒤 texinfo builder를 실행합니다. Sphinx가 생성한 `info` Make target은 `infodocs`가 `$(BUILDDIR)/texinfo`에서 실행합니다.

`linkcheckdocs`는 외부 link를 검사하는 builder를 각 directory에 적용합니다. `latexdocs`는 LaTeX source를 만듭니다.

PDF tool이 없으면 `pdfdocs`는 설치 warning을 내고 target을 skip합니다. Tool이 있으면 `pdfdocs`가 `latexdocs`에 의존하고, variable font를 차단하는 `XDG_CONFIG_HOME`을 설정합니다.

각 Sphinx directory의 LaTeX output에서 PDF build를 실행합니다. 실패하면 `check-variable-fonts.sh`로 variable font 문제를 확인하고, `pdf` directory를 만든 뒤 생성된 `.pdf`를 옮깁니다.

# 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

pdfdocs: DENY_VF = XDG_CONFIG_HOME=$(FONTS_CONF_DENY_VF)
pdfdocs: latexdocs
        @$(srctree)/scripts/sphinx-pre-install --version-check
        $(foreach var,$(SPHINXDIRS), \

EPUB·XML과 Sphinx 조건 종료

`epubdocs`는 version check 후 각 `SPHINXDIRS`를 `epub` builder로 처리하고 destination도 `epub` subfolder로 지정합니다.

`xmldocs`는 같은 방식으로 `xml` builder를 실행해 XML output을 만듭니다.

여기서 `HAVE_SPHINX` 조건부 block이 끝납니다. 이후 target은 Sphinx 존재와 무관하게 동작하거나 Sphinx 없이 조용히 통과하도록 작성됩니다.

           $(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.

독립 target과 dochelp

`refcheckdocs`는 source tree root에서 `scripts/documentation-file-ref-check`를 실행해 존재하지 않는 file reference를 검사합니다. `cleandocs`는 `$(BUILDDIR)`을 제거합니다.

`dochelp`는 사용 가능한 documentation target과 의미를 출력합니다. HTML, redirect, Texinfo, Info, LaTeX, PDF, EPUB, XML, external link check, internal file reference check, clean target을 안내합니다.

또한 `make SPHINXDIRS="s1 s2" [target]`으로 특정 folder만 생성하는 방법과 유효한 directory 목록을 보여 줍니다.

`SPHINX_CONF={conf-file}`로 추가 Sphinx config를 사용하고, `DOCS_THEME={sphinx-theme}`로 theme를 고르며, `DOCS_CSS={a .css file}`로 html·epub CSS override를 추가할 수 있습니다.

생성 문서의 기본 위치는 `Documentation/output`입니다.

refcheckdocs:
        $(Q)cd $(srctree);scripts/documentation-file-ref-check

cleandocs:
        $(Q)rm -rf $(BUILDDIR)

dochelp:
        @echo  ' Linux kernel internal documentation in different formats from ReST:'
        @echo  '  htmldocs        - HTML'
        @echo  '  htmldocs-redirects - generate HTML redirects for moved pages'
        @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'