tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
docs: remove DocBook from the building system
Now that we don't have any DocBook anymore, remove it from
the building system.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
+132
-277
-4
Documentation/00-INDEX
-4
Documentation/00-INDEX
···
24
24
- How to do DMA with ISA (and LPC) devices.
25
25
DMA-attributes.txt
26
26
- listing of the various possible attributes a DMA region can have
27
-
DocBook/
28
-
- directory with DocBook templates etc. for kernel documentation.
29
27
EDID/
30
28
- directory with info on customizing EDID for broken gfx/displays.
31
29
IPMI.txt
···
37
39
Intel-IOMMU.txt
38
40
- basic info on the Intel IOMMU virtualization support.
39
41
Makefile
40
-
- It's not of interest for those who aren't touching the build system.
41
-
Makefile.sphinx
42
42
- It's not of interest for those who aren't touching the build system.
43
43
PCI/
44
44
- info related to PCI drivers.
-17
Documentation/DocBook/.gitignore
-17
Documentation/DocBook/.gitignore
-1
Documentation/DocBook/Makefile
-1
Documentation/DocBook/Makefile
···
1
-
-11
Documentation/DocBook/stylesheet.xsl
-11
Documentation/DocBook/stylesheet.xsl
···
1
-
<?xml version="1.0" encoding="UTF-8"?>
2
-
<stylesheet xmlns="http://www.w3.org/1999/XSL/Transform" version="1.0">
3
-
<param name="chunk.quietly">1</param>
4
-
<param name="funcsynopsis.style">ansi</param>
5
-
<param name="funcsynopsis.tabular.threshold">80</param>
6
-
<param name="callout.graphics">0</param>
7
-
<!-- <param name="paper.type">A4</param> -->
8
-
<param name="generate.consistent.ids">1</param>
9
-
<param name="generate.section.toc.level">2</param>
10
-
<param name="use.id.as.filename">1</param>
11
-
</stylesheet>
+125
Documentation/Makefile
+125
Documentation/Makefile
···
1
+
# -*- makefile -*-
2
+
# Makefile for Sphinx documentation
3
+
#
4
+
1
5
subdir-y :=
6
+
7
+
# You can set these variables from the command line.
8
+
SPHINXBUILD = sphinx-build
9
+
SPHINXOPTS =
10
+
SPHINXDIRS = .
11
+
_SPHINXDIRS = $(patsubst $(srctree)/Documentation/%/conf.py,%,$(wildcard $(srctree)/Documentation/*/conf.py))
12
+
SPHINX_CONF = conf.py
13
+
PAPER =
14
+
BUILDDIR = $(obj)/output
15
+
PDFLATEX = xelatex
16
+
LATEXOPTS = -interaction=batchmode
17
+
18
+
# User-friendly check for sphinx-build
19
+
HAVE_SPHINX := $(shell if which $(SPHINXBUILD) >/dev/null 2>&1; then echo 1; else echo 0; fi)
20
+
21
+
ifeq ($(HAVE_SPHINX),0)
22
+
23
+
.DEFAULT:
24
+
$(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.)
25
+
@echo " SKIP Sphinx $@ target."
26
+
27
+
else # HAVE_SPHINX
28
+
29
+
# User-friendly check for pdflatex
30
+
HAVE_PDFLATEX := $(shell if which $(PDFLATEX) >/dev/null 2>&1; then echo 1; else echo 0; fi)
31
+
32
+
# Internal variables.
33
+
PAPEROPT_a4 = -D latex_paper_size=a4
34
+
PAPEROPT_letter = -D latex_paper_size=letter
35
+
KERNELDOC = $(srctree)/scripts/kernel-doc
36
+
KERNELDOC_CONF = -D kerneldoc_srctree=$(srctree) -D kerneldoc_bin=$(KERNELDOC)
37
+
ALLSPHINXOPTS = $(KERNELDOC_CONF) $(PAPEROPT_$(PAPER)) $(SPHINXOPTS)
38
+
# the i18n builder cannot share the environment and doctrees with the others
39
+
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
40
+
41
+
# commands; the 'cmd' from scripts/Kbuild.include is not *loopable*
42
+
loop_cmd = $(echo-cmd) $(cmd_$(1)) || exit;
43
+
44
+
# $2 sphinx builder e.g. "html"
45
+
# $3 name of the build subfolder / e.g. "media", used as:
46
+
# * dest folder relative to $(BUILDDIR) and
47
+
# * cache folder relative to $(BUILDDIR)/.doctrees
48
+
# $4 dest subfolder e.g. "man" for man pages at media/man
49
+
# $5 reST source folder relative to $(srctree)/$(src),
50
+
# e.g. "media" for the linux-tv book-set at ./Documentation/media
51
+
52
+
quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4)
53
+
cmd_sphinx = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/media $2 && \
54
+
PYTHONDONTWRITEBYTECODE=1 \
55
+
BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(srctree)/$(src)/$5/$(SPHINX_CONF)) \
56
+
$(SPHINXBUILD) \
57
+
-b $2 \
58
+
-c $(abspath $(srctree)/$(src)) \
59
+
-d $(abspath $(BUILDDIR)/.doctrees/$3) \
60
+
-D version=$(KERNELVERSION) -D release=$(KERNELRELEASE) \
61
+
$(ALLSPHINXOPTS) \
62
+
$(abspath $(srctree)/$(src)/$5) \
63
+
$(abspath $(BUILDDIR)/$3/$4)
64
+
65
+
htmldocs:
66
+
@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var)))
67
+
68
+
linkcheckdocs:
69
+
@$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,linkcheck,$(var),,$(var)))
70
+
71
+
latexdocs:
72
+
@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,latex,$(var),latex,$(var)))
73
+
74
+
ifeq ($(HAVE_PDFLATEX),0)
75
+
76
+
pdfdocs:
77
+
$(warning The '$(PDFLATEX)' command was not found. Make sure you have it installed and in PATH to produce PDF output.)
78
+
@echo " SKIP Sphinx $@ target."
79
+
80
+
else # HAVE_PDFLATEX
81
+
82
+
pdfdocs: latexdocs
83
+
$(foreach var,$(SPHINXDIRS), $(MAKE) PDFLATEX=$(PDFLATEX) LATEXOPTS="$(LATEXOPTS)" -C $(BUILDDIR)/$(var)/latex || exit;)
84
+
85
+
endif # HAVE_PDFLATEX
86
+
87
+
epubdocs:
88
+
@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,epub,$(var),epub,$(var)))
89
+
90
+
xmldocs:
91
+
@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,xml,$(var),xml,$(var)))
92
+
93
+
endif # HAVE_SPHINX
94
+
95
+
# The following targets are independent of HAVE_SPHINX, and the rules should
96
+
# work or silently pass without Sphinx.
97
+
98
+
# no-ops for the Sphinx toolchain
99
+
sgmldocs:
100
+
@:
101
+
psdocs:
102
+
@:
103
+
mandocs:
104
+
@:
105
+
installmandocs:
106
+
@:
107
+
108
+
cleandocs:
109
+
$(Q)rm -rf $(BUILDDIR)
110
+
$(Q)$(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/media clean
111
+
112
+
dochelp:
113
+
@echo ' Linux kernel internal documentation in different formats from ReST:'
114
+
@echo ' htmldocs - HTML'
115
+
@echo ' latexdocs - LaTeX'
116
+
@echo ' pdfdocs - PDF'
117
+
@echo ' epubdocs - EPUB'
118
+
@echo ' xmldocs - XML'
119
+
@echo ' linkcheckdocs - check for broken external links (will connect to external hosts)'
120
+
@echo ' cleandocs - clean all generated files'
121
+
@echo
122
+
@echo ' make SPHINXDIRS="s1 s2" [target] Generate only docs of folder s1, s2'
123
+
@echo ' valid values for SPHINXDIRS are: $(_SPHINXDIRS)'
124
+
@echo
125
+
@echo ' make SPHINX_CONF={conf-file} [target] use *additional* sphinx-build'
126
+
@echo ' configuration. This is e.g. useful to build with nit-picking config.'
-130
Documentation/Makefile.sphinx
-130
Documentation/Makefile.sphinx
···
1
-
# -*- makefile -*-
2
-
# Makefile for Sphinx documentation
3
-
#
4
-
5
-
# You can set these variables from the command line.
6
-
SPHINXBUILD = sphinx-build
7
-
SPHINXOPTS =
8
-
SPHINXDIRS = .
9
-
_SPHINXDIRS = $(patsubst $(srctree)/Documentation/%/conf.py,%,$(wildcard $(srctree)/Documentation/*/conf.py))
10
-
SPHINX_CONF = conf.py
11
-
PAPER =
12
-
BUILDDIR = $(obj)/output
13
-
PDFLATEX = xelatex
14
-
LATEXOPTS = -interaction=batchmode
15
-
16
-
# User-friendly check for sphinx-build
17
-
HAVE_SPHINX := $(shell if which $(SPHINXBUILD) >/dev/null 2>&1; then echo 1; else echo 0; fi)
18
-
19
-
ifeq ($(HAVE_SPHINX),0)
20
-
21
-
.DEFAULT:
22
-
$(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.)
23
-
@echo " SKIP Sphinx $@ target."
24
-
25
-
else ifneq ($(DOCBOOKS),)
26
-
27
-
# Skip Sphinx build if the user explicitly requested DOCBOOKS.
28
-
.DEFAULT:
29
-
@echo " SKIP Sphinx $@ target (DOCBOOKS specified)."
30
-
31
-
else # HAVE_SPHINX
32
-
33
-
# User-friendly check for pdflatex
34
-
HAVE_PDFLATEX := $(shell if which $(PDFLATEX) >/dev/null 2>&1; then echo 1; else echo 0; fi)
35
-
36
-
# Internal variables.
37
-
PAPEROPT_a4 = -D latex_paper_size=a4
38
-
PAPEROPT_letter = -D latex_paper_size=letter
39
-
KERNELDOC = $(srctree)/scripts/kernel-doc
40
-
KERNELDOC_CONF = -D kerneldoc_srctree=$(srctree) -D kerneldoc_bin=$(KERNELDOC)
41
-
ALLSPHINXOPTS = $(KERNELDOC_CONF) $(PAPEROPT_$(PAPER)) $(SPHINXOPTS)
42
-
# the i18n builder cannot share the environment and doctrees with the others
43
-
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
44
-
45
-
# commands; the 'cmd' from scripts/Kbuild.include is not *loopable*
46
-
loop_cmd = $(echo-cmd) $(cmd_$(1)) || exit;
47
-
48
-
# $2 sphinx builder e.g. "html"
49
-
# $3 name of the build subfolder / e.g. "media", used as:
50
-
# * dest folder relative to $(BUILDDIR) and
51
-
# * cache folder relative to $(BUILDDIR)/.doctrees
52
-
# $4 dest subfolder e.g. "man" for man pages at media/man
53
-
# $5 reST source folder relative to $(srctree)/$(src),
54
-
# e.g. "media" for the linux-tv book-set at ./Documentation/media
55
-
56
-
quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4)
57
-
cmd_sphinx = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/media $2 && \
58
-
PYTHONDONTWRITEBYTECODE=1 \
59
-
BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(srctree)/$(src)/$5/$(SPHINX_CONF)) \
60
-
$(SPHINXBUILD) \
61
-
-b $2 \
62
-
-c $(abspath $(srctree)/$(src)) \
63
-
-d $(abspath $(BUILDDIR)/.doctrees/$3) \
64
-
-D version=$(KERNELVERSION) -D release=$(KERNELRELEASE) \
65
-
$(ALLSPHINXOPTS) \
66
-
$(abspath $(srctree)/$(src)/$5) \
67
-
$(abspath $(BUILDDIR)/$3/$4)
68
-
69
-
htmldocs:
70
-
@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var)))
71
-
72
-
linkcheckdocs:
73
-
@$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,linkcheck,$(var),,$(var)))
74
-
75
-
latexdocs:
76
-
@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,latex,$(var),latex,$(var)))
77
-
78
-
ifeq ($(HAVE_PDFLATEX),0)
79
-
80
-
pdfdocs:
81
-
$(warning The '$(PDFLATEX)' command was not found. Make sure you have it installed and in PATH to produce PDF output.)
82
-
@echo " SKIP Sphinx $@ target."
83
-
84
-
else # HAVE_PDFLATEX
85
-
86
-
pdfdocs: latexdocs
87
-
$(foreach var,$(SPHINXDIRS), $(MAKE) PDFLATEX=$(PDFLATEX) LATEXOPTS="$(LATEXOPTS)" -C $(BUILDDIR)/$(var)/latex || exit;)
88
-
89
-
endif # HAVE_PDFLATEX
90
-
91
-
epubdocs:
92
-
@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,epub,$(var),epub,$(var)))
93
-
94
-
xmldocs:
95
-
@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,xml,$(var),xml,$(var)))
96
-
97
-
endif # HAVE_SPHINX
98
-
99
-
# The following targets are independent of HAVE_SPHINX, and the rules should
100
-
# work or silently pass without Sphinx.
101
-
102
-
# no-ops for the Sphinx toolchain
103
-
sgmldocs:
104
-
@:
105
-
psdocs:
106
-
@:
107
-
mandocs:
108
-
@:
109
-
installmandocs:
110
-
@:
111
-
112
-
cleandocs:
113
-
$(Q)rm -rf $(BUILDDIR)
114
-
$(Q)$(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/media clean
115
-
116
-
dochelp:
117
-
@echo ' Linux kernel internal documentation in different formats (Sphinx):'
118
-
@echo ' htmldocs - HTML'
119
-
@echo ' latexdocs - LaTeX'
120
-
@echo ' pdfdocs - PDF'
121
-
@echo ' epubdocs - EPUB'
122
-
@echo ' xmldocs - XML'
123
-
@echo ' linkcheckdocs - check for broken external links (will connect to external hosts)'
124
-
@echo ' cleandocs - clean all generated files'
125
-
@echo
126
-
@echo ' make SPHINXDIRS="s1 s2" [target] Generate only docs of folder s1, s2'
127
-
@echo ' valid values for SPHINXDIRS are: $(_SPHINXDIRS)'
128
-
@echo
129
-
@echo ' make SPHINX_CONF={conf-file} [target] use *additional* sphinx-build'
130
-
@echo ' configuration. This is e.g. useful to build with nit-picking config.'
-90
Documentation/doc-guide/docbook.rst
-90
Documentation/doc-guide/docbook.rst
···
1
-
DocBook XML [DEPRECATED]
2
-
========================
3
-
4
-
.. attention::
5
-
6
-
This section describes the deprecated DocBook XML toolchain. Please do not
7
-
create new DocBook XML template files. Please consider converting existing
8
-
DocBook XML templates files to Sphinx/reStructuredText.
9
-
10
-
Converting DocBook to Sphinx
11
-
----------------------------
12
-
13
-
Over time, we expect all of the documents under ``Documentation/DocBook`` to be
14
-
converted to Sphinx and reStructuredText. For most DocBook XML documents, a good
15
-
enough solution is to use the simple ``Documentation/sphinx/tmplcvt`` script,
16
-
which uses ``pandoc`` under the hood. For example::
17
-
18
-
$ cd Documentation/sphinx
19
-
$ ./tmplcvt ../DocBook/in.tmpl ../out.rst
20
-
21
-
Then edit the resulting rst files to fix any remaining issues, and add the
22
-
document in the ``toctree`` in ``Documentation/index.rst``.
23
-
24
-
Components of the kernel-doc system
25
-
-----------------------------------
26
-
27
-
Many places in the source tree have extractable documentation in the form of
28
-
block comments above functions. The components of this system are:
29
-
30
-
- ``scripts/kernel-doc``
31
-
32
-
This is a perl script that hunts for the block comments and can mark them up
33
-
directly into reStructuredText, DocBook, man, text, and HTML. (No, not
34
-
texinfo.)
35
-
36
-
- ``Documentation/DocBook/*.tmpl``
37
-
38
-
These are XML template files, which are normal XML files with special
39
-
place-holders for where the extracted documentation should go.
40
-
41
-
- ``scripts/docproc.c``
42
-
43
-
This is a program for converting XML template files into XML files. When a
44
-
file is referenced it is searched for symbols exported (EXPORT_SYMBOL), to be
45
-
able to distinguish between internal and external functions.
46
-
47
-
It invokes kernel-doc, giving it the list of functions that are to be
48
-
documented.
49
-
50
-
Additionally it is used to scan the XML template files to locate all the files
51
-
referenced herein. This is used to generate dependency information as used by
52
-
make.
53
-
54
-
- ``Makefile``
55
-
56
-
The targets 'xmldocs', 'psdocs', 'pdfdocs', and 'htmldocs' are used to build
57
-
DocBook XML files, PostScript files, PDF files, and html files in
58
-
Documentation/DocBook. The older target 'sgmldocs' is equivalent to 'xmldocs'.
59
-
60
-
- ``Documentation/DocBook/Makefile``
61
-
62
-
This is where C files are associated with SGML templates.
63
-
64
-
How to use kernel-doc comments in DocBook XML template files
65
-
------------------------------------------------------------
66
-
67
-
DocBook XML template files (\*.tmpl) are like normal XML files, except that they
68
-
can contain escape sequences where extracted documentation should be inserted.
69
-
70
-
``!E<filename>`` is replaced by the documentation, in ``<filename>``, for
71
-
functions that are exported using ``EXPORT_SYMBOL``: the function list is
72
-
collected from files listed in ``Documentation/DocBook/Makefile``.
73
-
74
-
``!I<filename>`` is replaced by the documentation for functions that are **not**
75
-
exported using ``EXPORT_SYMBOL``.
76
-
77
-
``!D<filename>`` is used to name additional files to search for functions
78
-
exported using ``EXPORT_SYMBOL``.
79
-
80
-
``!F<filename> <function [functions...]>`` is replaced by the documentation, in
81
-
``<filename>``, for the functions listed.
82
-
83
-
``!P<filename> <section title>`` is replaced by the contents of the ``DOC:``
84
-
section titled ``<section title>`` from ``<filename>``. Spaces are allowed in
85
-
``<section title>``; do not quote the ``<section title>``.
86
-
87
-
``!C<filename>`` is replaced by nothing, but makes the tools check that all DOC:
88
-
sections and documented functions, symbols, etc. are used. This makes sense to
89
-
use when you use ``!F`` or ``!P`` only and want to verify that all documentation
90
-
is included.
+4
-7
Makefile
+4
-7
Makefile
···
1298
1298
#
1299
1299
mrproper: rm-dirs := $(wildcard $(MRPROPER_DIRS))
1300
1300
mrproper: rm-files := $(wildcard $(MRPROPER_FILES))
1301
-
mrproper-dirs := $(addprefix _mrproper_,Documentation/DocBook scripts)
1301
+
mrproper-dirs := $(addprefix _mrproper_,scripts)
1302
1302
1303
1303
PHONY += $(mrproper-dirs) mrproper archmrproper
1304
1304
$(mrproper-dirs):
···
1400
1400
@$(MAKE) $(build)=$(package-dir) help
1401
1401
@echo ''
1402
1402
@echo 'Documentation targets:'
1403
-
@$(MAKE) -f $(srctree)/Documentation/Makefile.sphinx dochelp
1404
-
@echo ''
1405
-
@$(MAKE) -f $(srctree)/Documentation/DocBook/Makefile dochelp
1403
+
@$(MAKE) -f $(srctree)/Documentation/Makefile dochelp
1406
1404
@echo ''
1407
1405
@echo 'Architecture specific targets ($(SRCARCH)):'
1408
1406
@$(if $(archhelp),$(archhelp),\
···
1451
1453
DOC_TARGETS := xmldocs sgmldocs psdocs latexdocs pdfdocs htmldocs mandocs installmandocs epubdocs cleandocs linkcheckdocs
1452
1454
PHONY += $(DOC_TARGETS)
1453
1455
$(DOC_TARGETS): scripts_basic FORCE
1454
-
$(Q)$(MAKE) $(build)=scripts build_docproc build_check-lc_ctype
1455
-
$(Q)$(MAKE) $(build)=Documentation -f $(srctree)/Documentation/Makefile.sphinx $@
1456
-
$(Q)$(MAKE) $(build)=Documentation/DocBook $@
1456
+
$(Q)$(MAKE) $(build)=scripts build_docproc
1457
+
$(Q)$(MAKE) $(build)=Documentation $@
1457
1458
1458
1459
else # KBUILD_EXTMOD
1459
1460
+3
-6
scripts/Makefile
+3
-6
scripts/Makefile
···
6
6
# pnmttologo: Convert pnm files to logo files
7
7
# conmakehash: Create chartable
8
8
# conmakehash: Create arrays for initializing the kernel console tables
9
-
# docproc: Used in Documentation/DocBook
10
-
# check-lc_ctype: Used in Documentation/DocBook
9
+
# docproc: Used in Documentation/
11
10
12
11
HOST_EXTRACFLAGS += -I$(srctree)/tools/include
13
12
···
28
29
always := $(hostprogs-y) $(hostprogs-m)
29
30
30
31
# The following hostprogs-y programs are only build on demand
31
-
hostprogs-y += unifdef docproc check-lc_ctype
32
+
hostprogs-y += unifdef docproc
32
33
33
34
# These targets are used internally to avoid "is up to date" messages
34
-
PHONY += build_unifdef build_docproc build_check-lc_ctype
35
+
PHONY += build_unifdef build_docproc
35
36
build_unifdef: $(obj)/unifdef
36
37
@:
37
38
build_docproc: $(obj)/docproc
38
-
@:
39
-
build_check-lc_ctype: $(obj)/check-lc_ctype
40
39
@:
41
40
42
41
subdir-$(CONFIG_MODVERSIONS) += genksyms