2017-05-14 08:50:01 -06:00
# -*- makefile -*-
# Makefile for Sphinx documentation
#
2020-02-26 10:53:25 -07:00
# for cleaning
subdir- := devicetree/bindings
2017-05-14 08:50:01 -06:00
2019-06-04 06:26:27 -06:00
# Check for broken documentation file references
i f e q ( $( CONFIG_WARN_MISSING_DOCUMENTS ) , y )
$( shell $ ( srctree ) /scripts /documentation -file -ref -check --warn )
e n d i f
2017-05-14 08:50:01 -06:00
# You can set these variables from the command line.
SPHINXBUILD = sphinx-build
SPHINXOPTS =
SPHINXDIRS = .
2020-02-16 00:26:06 -07:00
_SPHINXDIRS = $( sort $( patsubst $( srctree) /Documentation/%/index.rst,%,$( wildcard $( srctree) /Documentation/*/index.rst) ) )
2017-05-14 08:50:01 -06:00
SPHINX_CONF = conf.py
PAPER =
BUILDDIR = $( obj) /output
PDFLATEX = xelatex
LATEXOPTS = -interaction= batchmode
# User-friendly check for sphinx-build
HAVE_SPHINX := $( shell if which $( SPHINXBUILD) >/dev/null 2>& 1; then echo 1; else echo 0; fi )
i f e q ( $( 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.)
2017-07-16 16:08:06 -06:00
@echo
2019-05-31 10:02:11 -06:00
@$( srctree) /scripts/sphinx-pre-install
2017-05-14 08:50:01 -06:00
@echo " SKIP Sphinx $@ target. "
e l s e # HAVE_SPHINX
2019-03-30 07:45:58 -06:00
# User-friendly check for pdflatex and latexmk
2017-05-14 08:50:01 -06:00
HAVE_PDFLATEX := $( shell if which $( PDFLATEX) >/dev/null 2>& 1; then echo 1; else echo 0; fi )
2019-03-30 07:45:58 -06:00
HAVE_LATEXMK := $( shell if which latexmk >/dev/null 2>& 1; then echo 1; else echo 0; fi )
i f e q ( $( HAVE_LATEXMK ) , 1 )
PDFLATEX := latexmk -$( PDFLATEX)
e n d i f #HAVE_LATEXMK
2017-05-14 08:50:01 -06:00
# 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)
# 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"
2020-03-04 02:21:39 -07:00
# $3 name of the build subfolder / e.g. "userspace-api/media", used as:
2017-05-14 08:50:01 -06:00
# * dest folder relative to $(BUILDDIR) and
# * cache folder relative to $(BUILDDIR)/.doctrees
2020-03-04 02:21:39 -07:00
# $4 dest subfolder e.g. "man" for man pages at userspace-api/media/man
2017-05-14 08:50:01 -06:00
# $5 reST source folder relative to $(srctree)/$(src),
2020-03-04 02:21:39 -07:00
# e.g. "userspace-api/media" for the linux-tv book-set at ./Documentation/userspace-api/media
2017-05-14 08:50:01 -06:00
quiet_cmd_sphinx = SPHINX $@ --> file://$( abspath $( BUILDDIR) /$3 /$4 )
2020-03-04 02:21:39 -07:00
cmd_sphinx = $( MAKE) BUILDDIR = $( abspath $( BUILDDIR) ) $( build) = Documentation/userspace-api/media $2 && \
2017-05-14 08:50:01 -06:00
PYTHONDONTWRITEBYTECODE = 1 \
BUILDDIR = $( abspath $( BUILDDIR) ) SPHINX_CONF = $( abspath $( srctree) /$( src) /$5 /$( SPHINX_CONF) ) \
2019-11-21 13:59:29 -07:00
$( PYTHON) $( srctree) /scripts/jobserver-exec \
$( SHELL) $( srctree) /Documentation/sphinx/parallel-wrapper.sh \
2017-05-14 08:50:01 -06:00
$( SPHINXBUILD) \
-b $2 \
-c $( abspath $( srctree) /$( src) ) \
-d $( abspath $( BUILDDIR) /.doctrees/$3 ) \
-D version = $( KERNELVERSION) -D release = $( KERNELRELEASE) \
$( ALLSPHINXOPTS) \
$( abspath $( srctree) /$( src) /$5 ) \
$( abspath $( BUILDDIR) /$3 /$4 )
htmldocs :
2019-06-04 07:55:49 -06:00
@$( srctree) /scripts/sphinx-pre-install --version-check
2017-05-14 08:50:01 -06:00
@+$( foreach var,$( SPHINXDIRS) ,$( call loop_cmd,sphinx,html,$( var) ,,$( var) ) )
linkcheckdocs :
@$( foreach var,$( SPHINXDIRS) ,$( call loop_cmd,sphinx,linkcheck,$( var) ,,$( var) ) )
latexdocs :
2019-06-04 07:55:49 -06:00
@$( srctree) /scripts/sphinx-pre-install --version-check
2017-05-14 08:50:01 -06:00
@+$( foreach var,$( SPHINXDIRS) ,$( call loop_cmd,sphinx,latex,$( var) ,latex,$( var) ) )
i f e q ( $( 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. "
e l s e # HAVE_PDFLATEX
pdfdocs : latexdocs
2019-06-04 07:55:49 -06:00
@$( srctree) /scripts/sphinx-pre-install --version-check
2020-04-14 10:48:53 -06:00
$( foreach var,$( SPHINXDIRS) , \
$( MAKE) PDFLATEX = " $( PDFLATEX) " LATEXOPTS = " $( LATEXOPTS) " -C $( BUILDDIR) /$( var) /latex || exit; \
mkdir -p $( BUILDDIR) /$( var) /pdf; \
mv $( subst .tex,.pdf,$( wildcard $( BUILDDIR) /$( var) /latex/*.tex) ) $( BUILDDIR) /$( var) /pdf/; \
)
2017-05-14 08:50:01 -06:00
e n d i f # HAVE_PDFLATEX
epubdocs :
2019-06-04 07:55:49 -06:00
@$( srctree) /scripts/sphinx-pre-install --version-check
2017-05-14 08:50:01 -06:00
@+$( foreach var,$( SPHINXDIRS) ,$( call loop_cmd,sphinx,epub,$( var) ,epub,$( var) ) )
xmldocs :
2019-06-04 07:55:49 -06:00
@$( srctree) /scripts/sphinx-pre-install --version-check
2017-05-14 08:50:01 -06:00
@+$( foreach var,$( SPHINXDIRS) ,$( call loop_cmd,sphinx,xml,$( var) ,xml,$( var) ) )
e n d i f # HAVE_SPHINX
# The following targets are independent of HAVE_SPHINX, and the rules should
# work or silently pass without Sphinx.
2017-10-09 09:26:15 -06:00
refcheckdocs :
$( Q) cd $( srctree) ; scripts/documentation-file-ref-check
2017-05-14 08:50:01 -06:00
cleandocs :
$( Q) rm -rf $( BUILDDIR)
2020-03-04 02:21:39 -07:00
$( Q) $( MAKE) BUILDDIR = $( abspath $( BUILDDIR) ) $( build) = Documentation/userspace-api/media clean
2017-05-14 08:50:01 -06:00
dochelp :
@echo ' Linux kernel internal documentation in different formats from ReST:'
@echo ' htmldocs - HTML'
@echo ' latexdocs - LaTeX'
@echo ' pdfdocs - PDF'
@echo ' epubdocs - EPUB'
@echo ' xmldocs - XML'
2019-10-25 05:52:32 -06:00
@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'
2017-05-14 08:50:01 -06:00
@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.'
2017-10-02 17:44:18 -06:00
@echo
@echo ' Default location for the generated documents is Documentation/output'