Skip to content

Commit 78a88f7

Browse files
si-gdsystrini
si-gdsys
authored and
trini
committed
doc: Replace DocBook with sphinx-based docs
The Linux kernel moved to sphinx-based documentation and got rid of the DocBook based documentation quite a while ago. Hence, the DocBook documentation for U-Boot should be converted as well. To achieve this, import the necessary files from Linux v4.17, and convert the current DocBook documentation (three files altogether) to sphinx/reStructuredText. For now, all old DocBook documentation was merged into a single handbook, tentatively named "U-Boot Hacker Manual". For some source files, the documentation style was changed to comply with kernel-doc; no functional changes were applied. Signed-off-by: Mario Six <mario.six@gdsys.cc>
1 parent 5448ff3 commit 78a88f7

26 files changed

+4375
-2404
lines changed

‎Documentation/.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
output
2+
*.pyc

‎Documentation/Makefile‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
# -*- makefile -*-
2+
# Makefile for Sphinx documentation
3+
#
4+
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
26+
@./scripts/sphinx-pre-install
27+
@echo " SKIP Sphinx $@ target."
28+
29+
else # HAVE_SPHINX
30+
31+
# User-friendly check for pdflatex
32+
HAVE_PDFLATEX := $(shell if which $(PDFLATEX) >/dev/null 2>&1; then echo 1; else echo 0; fi)
33+
34+
# Internal variables.
35+
PAPEROPT_a4 = -D latex_paper_size=a4
36+
PAPEROPT_letter = -D latex_paper_size=letter
37+
KERNELDOC = $(srctree)/scripts/kernel-doc
38+
KERNELDOC_CONF = -D kerneldoc_srctree=$(srctree) -D kerneldoc_bin=$(KERNELDOC)
39+
ALLSPHINXOPTS = $(KERNELDOC_CONF) $(PAPEROPT_$(PAPER)) $(SPHINXOPTS)
40+
# the i18n builder cannot share the environment and doctrees with the others
41+
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
42+
43+
# commands; the 'cmd' from scripts/Kbuild.include is not *loopable*
44+
loop_cmd = $(echo-cmd) $(cmd_$(1)) || exit;
45+
46+
# $2 sphinx builder e.g. "html"
47+
# $3 name of the build subfolder / e.g. "media", used as:
48+
# * dest folder relative to $(BUILDDIR) and
49+
# * cache folder relative to $(BUILDDIR)/.doctrees
50+
# $4 dest subfolder e.g. "man" for man pages at media/man
51+
# $5 reST source folder relative to $(srctree)/$(src),
52+
# e.g. "media" for the linux-tv book-set at ./Documentation/media
53+
54+
quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4)
55+
cmd_sphinx = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/media $2 && \
56+
PYTHONDONTWRITEBYTECODE=1 \
57+
BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(srctree)/$(src)/$5/$(SPHINX_CONF)) \
58+
$(SPHINXBUILD) \
59+
-b $2 \
60+
-c $(abspath $(srctree)/$(src)) \
61+
-d $(abspath $(BUILDDIR)/.doctrees/$3) \
62+
-D version=$(KERNELVERSION) -D release=$(KERNELRELEASE) \
63+
$(ALLSPHINXOPTS) \
64+
$(abspath $(srctree)/$(src)/$5) \
65+
$(abspath $(BUILDDIR)/$3/$4)
66+
67+
htmldocs:
68+
@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var)))
69+
70+
linkcheckdocs:
71+
@$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,linkcheck,$(var),,$(var)))
72+
73+
latexdocs:
74+
@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,latex,$(var),latex,$(var)))
75+
76+
ifeq ($(HAVE_PDFLATEX),0)
77+
78+
pdfdocs:
79+
$(warning The '$(PDFLATEX)' command was not found. Make sure you have it installed and in PATH to produce PDF output.)
80+
@echo " SKIP Sphinx $@ target."
81+
82+
else # HAVE_PDFLATEX
83+
84+
pdfdocs: latexdocs
85+
$(foreach var,$(SPHINXDIRS), $(MAKE) PDFLATEX=$(PDFLATEX) LATEXOPTS="$(LATEXOPTS)" -C $(BUILDDIR)/$(var)/latex || exit;)
86+
87+
endif # HAVE_PDFLATEX
88+
89+
epubdocs:
90+
@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,epub,$(var),epub,$(var)))
91+
92+
xmldocs:
93+
@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,xml,$(var),xml,$(var)))
94+
95+
endif # HAVE_SPHINX
96+
97+
# The following targets are independent of HAVE_SPHINX, and the rules should
98+
# work or silently pass without Sphinx.
99+
100+
refcheckdocs:
101+
$(Q)cd $(srctree);scripts/documentation-file-ref-check
102+
103+
cleandocs:
104+
$(Q)rm -rf $(BUILDDIR)
105+
$(Q)$(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/media clean
106+
107+
dochelp:
108+
@echo ' Linux kernel internal documentation in different formats from ReST:'
109+
@echo ' htmldocs - HTML'
110+
@echo ' latexdocs - LaTeX'
111+
@echo ' pdfdocs - PDF'
112+
@echo ' epubdocs - EPUB'
113+
@echo ' xmldocs - XML'
114+
@echo ' linkcheckdocs - check for broken external links (will connect to external hosts)'
115+
@echo ' refcheckdocs - check for references to non-existing files under Documentation'
116+
@echo ' cleandocs - clean all generated files'
117+
@echo
118+
@echo ' make SPHINXDIRS="s1 s2" [target] Generate only docs of folder s1, s2'
119+
@echo ' valid values for SPHINXDIRS are: $(_SPHINXDIRS)'
120+
@echo
121+
@echo ' make SPHINX_CONF={conf-file} [target] use *additional* sphinx-build'
122+
@echo ' configuration. This is e.g. useful to build with nit-picking config.'
123+
@echo
124+
@echo ' Default location for the generated documents is Documentation/output'

0 commit comments

Comments
 (0)