redonkable
/
alistair23-linux
1
0
Fork 0
Code Releases Activity

sphinx.rst: explain the usage of virtual environment 

As the Sphinx build seems very fragile, specially for
PDF output, add a notice about how to use it on a virtual
environment.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
hifive-unleashed-5.1
Mauro Carvalho Chehab 2017-07-14 13:41:18 -03:00 committed by Jonathan Corbet
parent b8b07b5c8d
commit 58ef4a42dd
1 changed files with 32 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
Documentation/doc-guide/sphinx.rst
View File

@ -28,6 +28,38 @@ 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
PDF outputs, it is recommended to use version 1.4.6 or upper.
Most distributions are shipped with Sphinx, but its toolchain is fragile,
and it is not uncommon that upgrading it or some other Python packages
on your machine would cause the documentation build to break.
A way to get rid of that is to use a different version than the one shipped
on your distributions. In order to do that, it is recommended to install
Sphinx inside a virtual environment, using ``virtualenv-3``
or ``virtualenv``, depending on how your distribution packaged Python 3.
.. note::
#) Sphinx versions below 1.5 don't work properly with Python's
docutils version 0.13.1 or upper. So, if you're willing to use
those versions, you should run ``pip install 'docutils==0.12'``.
#) It is recommended to use the RTD theme for html output. Depending
on the Sphinx version, it should be installed in separate,
with ``pip install sphinx_rtd_theme``.
In summary, if you want to install Sphinx version 1.4.9, you should do::
$ virtualenv sphinx_1.4
$ . sphinx_1.4/bin/activate
(sphinx_1.4) $ pip install 'docutils==0.12'
(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,
in order to indicate that you're using the new environment. If you
open a new shell, you need to rerun this command to enter again at
the virtual environment before building the documentation.
.. note::
Please notice that, for PDF and LaTeX output, you'll also need ``XeLaTeX``