Makefile 5.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157
  1. # -*- makefile -*-
  2. # Makefile for Sphinx documentation
  3. #
  4. # for cleaning
  5. subdir- := devicetree/bindings
  6. # Check for broken documentation file references
  7. ifeq ($(CONFIG_WARN_MISSING_DOCUMENTS),y)
  8. $(shell $(srctree)/scripts/documentation-file-ref-check --warn)
  9. endif
  10. # Check for broken ABI files
  11. ifeq ($(CONFIG_WARN_ABI_ERRORS),y)
  12. $(shell $(srctree)/scripts/get_abi.pl validate --dir $(srctree)/Documentation/ABI)
  13. endif
  14. # You can set these variables from the command line.
  15. SPHINXBUILD = sphinx-build
  16. SPHINXOPTS =
  17. SPHINXDIRS = .
  18. _SPHINXDIRS = $(sort $(patsubst $(srctree)/Documentation/%/index.rst,%,$(wildcard $(srctree)/Documentation/*/index.rst)))
  19. SPHINX_CONF = conf.py
  20. PAPER =
  21. BUILDDIR = $(obj)/output
  22. PDFLATEX = xelatex
  23. LATEXOPTS = -interaction=batchmode
  24. ifeq ($(KBUILD_VERBOSE),0)
  25. SPHINXOPTS += "-q"
  26. endif
  27. # User-friendly check for sphinx-build
  28. HAVE_SPHINX := $(shell if which $(SPHINXBUILD) >/dev/null 2>&1; then echo 1; else echo 0; fi)
  29. ifeq ($(HAVE_SPHINX),0)
  30. .DEFAULT:
  31. $(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.)
  32. @echo
  33. @$(srctree)/scripts/sphinx-pre-install
  34. @echo " SKIP Sphinx $@ target."
  35. else # HAVE_SPHINX
  36. # User-friendly check for pdflatex and latexmk
  37. HAVE_PDFLATEX := $(shell if which $(PDFLATEX) >/dev/null 2>&1; then echo 1; else echo 0; fi)
  38. HAVE_LATEXMK := $(shell if which latexmk >/dev/null 2>&1; then echo 1; else echo 0; fi)
  39. ifeq ($(HAVE_LATEXMK),1)
  40. PDFLATEX := latexmk -$(PDFLATEX)
  41. endif #HAVE_LATEXMK
  42. # Internal variables.
  43. PAPEROPT_a4 = -D latex_paper_size=a4
  44. PAPEROPT_letter = -D latex_paper_size=letter
  45. KERNELDOC = $(srctree)/scripts/kernel-doc
  46. KERNELDOC_CONF = -D kerneldoc_srctree=$(srctree) -D kerneldoc_bin=$(KERNELDOC)
  47. ALLSPHINXOPTS = $(KERNELDOC_CONF) $(PAPEROPT_$(PAPER)) $(SPHINXOPTS)
  48. # the i18n builder cannot share the environment and doctrees with the others
  49. I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
  50. # commands; the 'cmd' from scripts/Kbuild.include is not *loopable*
  51. loop_cmd = $(echo-cmd) $(cmd_$(1)) || exit;
  52. # $2 sphinx builder e.g. "html"
  53. # $3 name of the build subfolder / e.g. "userspace-api/media", used as:
  54. # * dest folder relative to $(BUILDDIR) and
  55. # * cache folder relative to $(BUILDDIR)/.doctrees
  56. # $4 dest subfolder e.g. "man" for man pages at userspace-api/media/man
  57. # $5 reST source folder relative to $(srctree)/$(src),
  58. # e.g. "userspace-api/media" for the linux-tv book-set at ./Documentation/userspace-api/media
  59. quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4)
  60. cmd_sphinx = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/userspace-api/media $2 && \
  61. PYTHONDONTWRITEBYTECODE=1 \
  62. BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(srctree)/$(src)/$5/$(SPHINX_CONF)) \
  63. $(PYTHON) $(srctree)/scripts/jobserver-exec \
  64. $(SHELL) $(srctree)/Documentation/sphinx/parallel-wrapper.sh \
  65. $(SPHINXBUILD) \
  66. -b $2 \
  67. -c $(abspath $(srctree)/$(src)) \
  68. -d $(abspath $(BUILDDIR)/.doctrees/$3) \
  69. -D version=$(KERNELVERSION) -D release=$(KERNELRELEASE) \
  70. $(ALLSPHINXOPTS) \
  71. $(abspath $(srctree)/$(src)/$5) \
  72. $(abspath $(BUILDDIR)/$3/$4)
  73. htmldocs:
  74. @$(srctree)/scripts/sphinx-pre-install --version-check
  75. @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var)))
  76. linkcheckdocs:
  77. @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,linkcheck,$(var),,$(var)))
  78. latexdocs:
  79. @$(srctree)/scripts/sphinx-pre-install --version-check
  80. @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,latex,$(var),latex,$(var)))
  81. ifeq ($(HAVE_PDFLATEX),0)
  82. pdfdocs:
  83. $(warning The '$(PDFLATEX)' command was not found. Make sure you have it installed and in PATH to produce PDF output.)
  84. @echo " SKIP Sphinx $@ target."
  85. else # HAVE_PDFLATEX
  86. pdfdocs: latexdocs
  87. @$(srctree)/scripts/sphinx-pre-install --version-check
  88. $(foreach var,$(SPHINXDIRS), \
  89. $(MAKE) PDFLATEX="$(PDFLATEX)" LATEXOPTS="$(LATEXOPTS)" -C $(BUILDDIR)/$(var)/latex || exit; \
  90. mkdir -p $(BUILDDIR)/$(var)/pdf; \
  91. mv $(subst .tex,.pdf,$(wildcard $(BUILDDIR)/$(var)/latex/*.tex)) $(BUILDDIR)/$(var)/pdf/; \
  92. )
  93. endif # HAVE_PDFLATEX
  94. epubdocs:
  95. @$(srctree)/scripts/sphinx-pre-install --version-check
  96. @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,epub,$(var),epub,$(var)))
  97. xmldocs:
  98. @$(srctree)/scripts/sphinx-pre-install --version-check
  99. @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,xml,$(var),xml,$(var)))
  100. endif # HAVE_SPHINX
  101. # The following targets are independent of HAVE_SPHINX, and the rules should
  102. # work or silently pass without Sphinx.
  103. refcheckdocs:
  104. $(Q)cd $(srctree);scripts/documentation-file-ref-check
  105. cleandocs:
  106. $(Q)rm -rf $(BUILDDIR)
  107. $(Q)$(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/userspace-api/media clean
  108. dochelp:
  109. @echo ' Linux kernel internal documentation in different formats from ReST:'
  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'
  116. @echo ' (will connect to external hosts)'
  117. @echo ' refcheckdocs - check for references to non-existing files under'
  118. @echo ' Documentation'
  119. @echo ' cleandocs - clean all generated files'
  120. @echo
  121. @echo ' make SPHINXDIRS="s1 s2" [target] Generate only docs of folder s1, s2'
  122. @echo ' valid values for SPHINXDIRS are: $(_SPHINXDIRS)'
  123. @echo
  124. @echo ' make SPHINX_CONF={conf-file} [target] use *additional* sphinx-build'
  125. @echo ' configuration. This is e.g. useful to build with nit-picking config.'
  126. @echo
  127. @echo ' Default location for the generated documents is Documentation/output'