Commit c7004d10 authored by Jonathan Corbet's avatar Jonathan Corbet

Merge branch 'install' into docs-next

Mauro says:

Sphinx installation is not trivial, as not all versions are supported,
and it requires a lot of stuff for math, images and PDF/LaTeX output
to work.

So, add a script that checks if everything is fine, providing
distro-specific hints about what's needed for it to work.
parents e604f1cb 800d408a
...@@ -95,16 +95,6 @@ endif # HAVE_SPHINX ...@@ -95,16 +95,6 @@ endif # HAVE_SPHINX
# The following targets are independent of HAVE_SPHINX, and the rules should # The following targets are independent of HAVE_SPHINX, and the rules should
# work or silently pass without Sphinx. # work or silently pass without Sphinx.
# no-ops for the Sphinx toolchain
sgmldocs:
@:
psdocs:
@:
mandocs:
@:
installmandocs:
@:
cleandocs: cleandocs:
$(Q)rm -rf $(BUILDDIR) $(Q)rm -rf $(BUILDDIR)
$(Q)$(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/media clean $(Q)$(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/media clean
......
...@@ -28,6 +28,9 @@ The ReST markups currently used by the Documentation/ files are meant to be ...@@ -28,6 +28,9 @@ The ReST markups currently used by the Documentation/ files are meant to be
built with ``Sphinx`` version 1.3 or upper. If you're desiring to build built with ``Sphinx`` version 1.3 or upper. If you're desiring to build
PDF outputs, it is recommended to use version 1.4.6 or upper. PDF outputs, it is recommended to use version 1.4.6 or upper.
There's a script that checks for the Spinx requirements. Please see
:ref:`sphinx-pre-install` for further details.
Most distributions are shipped with Sphinx, but its toolchain is fragile, Most distributions are shipped with Sphinx, but its toolchain is fragile,
and it is not uncommon that upgrading it or some other Python packages and it is not uncommon that upgrading it or some other Python packages
on your machine would cause the documentation build to break. on your machine would cause the documentation build to break.
...@@ -47,13 +50,15 @@ or ``virtualenv``, depending on how your distribution packaged Python 3. ...@@ -47,13 +50,15 @@ or ``virtualenv``, depending on how your distribution packaged Python 3.
on the Sphinx version, it should be installed in separate, on the Sphinx version, it should be installed in separate,
with ``pip install sphinx_rtd_theme``. with ``pip install sphinx_rtd_theme``.
#) Some ReST pages contain math expressions. Due to the way Sphinx work,
those expressions are written using LaTeX notation. It needs texlive
installed with amdfonts and amsmath in order to evaluate them.
In summary, if you want to install Sphinx version 1.4.9, you should do:: In summary, if you want to install Sphinx version 1.4.9, you should do::
$ virtualenv sphinx_1.4 $ virtualenv sphinx_1.4
$ . sphinx_1.4/bin/activate $ . sphinx_1.4/bin/activate
(sphinx_1.4) $ pip install 'docutils==0.12' (sphinx_1.4) $ pip install -r Documentation/sphinx/requirements.txt
(sphinx_1.4) $ pip install 'Sphinx==1.4.9'
(sphinx_1.4) $ pip install sphinx_rtd_theme
After running ``. sphinx_1.4/bin/activate``, the prompt will change, After running ``. sphinx_1.4/bin/activate``, the prompt will change,
in order to indicate that you're using the new environment. If you in order to indicate that you're using the new environment. If you
...@@ -83,7 +88,42 @@ For PDF and LaTeX output, you'll also need ``XeLaTeX`` version 3.14159265. ...@@ -83,7 +88,42 @@ For PDF and LaTeX output, you'll also need ``XeLaTeX`` version 3.14159265.
Depending on the distribution, you may also need to install a series of Depending on the distribution, you may also need to install a series of
``texlive`` packages that provide the minimal set of functionalities ``texlive`` packages that provide the minimal set of functionalities
required for ``XeLaTex`` to work. required for ``XeLaTeX`` to work.
.. _sphinx-pre-install:
Checking for Sphinx dependencies
--------------------------------
There's a script that automatically check for Sphinx dependencies. If it can
recognize your distribution, it will also give a hint about the install
command line options for your distro::
$ ./scripts/sphinx-pre-install
Checking if the needed tools for Fedora release 26 (Twenty Six) are available
Warning: better to also install "texlive-luatex85".
You should run:
sudo dnf install -y texlive-luatex85
/usr/bin/virtualenv sphinx_1.4
. sphinx_1.4/bin/activate
pip install -r Documentation/sphinx/requirements.txt
Can't build as 1 mandatory dependency is missing at ./scripts/sphinx-pre-install line 468.
By default, it checks all the requirements for both html and PDF, including
the requirements for images, math expressions and LaTeX build, and assumes
that a virtual Python environment will be used. The ones needed for html
builds are assumed to be mandatory; the others to be optional.
It supports two optional parameters:
``--no-pdf``
Disable checks for PDF;
``--no-virtualenv``
Use OS packaging for Sphinx instead of Python virtual environment.
Sphinx Build Sphinx Build
============ ============
......
docutils==0.12
Sphinx==1.4.9
sphinx_rtd_theme
...@@ -149,9 +149,7 @@ Linux内核代码中包含有大量的文档。这些文档对于学习如何与 ...@@ -149,9 +149,7 @@ Linux内核代码中包含有大量的文档。这些文档对于学习如何与
核源码的主目录中使用以下不同命令将会分别生成PDF、Postscript、HTML和手册 核源码的主目录中使用以下不同命令将会分别生成PDF、Postscript、HTML和手册
页等不同格式的文档: 页等不同格式的文档:
make pdfdocs make pdfdocs
make psdocs
make htmldocs make htmldocs
make mandocs
如何成为内核开发者 如何成为内核开发者
......
...@@ -1467,7 +1467,7 @@ $(help-board-dirs): help-%: ...@@ -1467,7 +1467,7 @@ $(help-board-dirs): help-%:
# Documentation targets # Documentation targets
# --------------------------------------------------------------------------- # ---------------------------------------------------------------------------
DOC_TARGETS := xmldocs sgmldocs psdocs latexdocs pdfdocs htmldocs mandocs installmandocs epubdocs cleandocs linkcheckdocs DOC_TARGETS := xmldocs latexdocs pdfdocs htmldocs epubdocs cleandocs linkcheckdocs
PHONY += $(DOC_TARGETS) PHONY += $(DOC_TARGETS)
$(DOC_TARGETS): scripts_basic FORCE $(DOC_TARGETS): scripts_basic FORCE
$(Q)$(MAKE) $(build)=Documentation $@ $(Q)$(MAKE) $(build)=Documentation $@
......
This diff is collapsed.
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment