The Sphinx build chain is fragile: any upgrades can cause it to break.
That's what happened this week, when I upgraded my machines to
Fedora 26.
So, add a separate chapter at sphinx.rst with Sphinx install instructions,
moving it out of changes.rst.
Mauro Carvalho Chehab (6):
changes.rst: Update Sphinx minimal requirements
docs-rst: update Sphinx install instructions
sphinx.rst: explain the usage of virtual environment
sphinx.rst: fix unknown reference
sphinx.rst: describe the install requirements for kfigure
sphinx.rst: better organize the documentation about PDF build
Documentation/doc-guide/sphinx.rst | 69 +++++++++++++++++++++++++++++++++++++-
Documentation/process/changes.rst | 16 ++-------
2 files changed, 71 insertions(+), 14 deletions(-)
--
2.13.0
There's no "Sphinx C Domain" reference at the Kernel
documentation. So, don't use references for it.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
Documentation/doc-guide/sphinx.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst
index 3278262164da..4c6cb454eaa0 100644
--- a/Documentation/doc-guide/sphinx.rst
+++ b/Documentation/doc-guide/sphinx.rst
@@ -167,7 +167,7 @@ Here are some specific guidelines for the kernel documentation:
the C domain
------------
-The `Sphinx C Domain`_ (name c) is suited for documentation of C API. E.g. a
+The **Sphinx C Domain** (name c) is suited for documentation of C API. E.g. a
function prototype:
.. code-block:: rst
--
2.13.0
Instead of having it on just one note, add a separate section.
This way, we could later improve it, providing a better
guide about the needed steps for PDF builds.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
Documentation/doc-guide/sphinx.rst | 21 +++++++++++++--------
1 file changed, 13 insertions(+), 8 deletions(-)
diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst
index 3a41483ed499..5521213efa68 100644
--- a/Documentation/doc-guide/sphinx.rst
+++ b/Documentation/doc-guide/sphinx.rst
@@ -60,14 +60,6 @@ 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``
- version 3.14159265. Depending on the distribution, you may also need to
- install a series of ``texlive`` packages that provide the minimal set of
- functionalities required for ``XeLaTex`` to work. For PDF output you'll also
- need ``convert(1)`` from ImageMagick (https://www.imagemagick.org).
-
Image output
------------
@@ -80,6 +72,19 @@ packages. If those packages are not installed, the build system will
still build the documentation, but won't include any images at the
output.
+PDF and LaTeX builds
+--------------------
+
+Such builds are currently supported only with Sphinx versions 1.4 and 1.5.
+
+Currently, it is not possible to do pdf builds with Sphinx version 1.6.
+
+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
+``texlive`` packages that provide the minimal set of functionalities
+required for ``XeLaTex`` to work.
+
Sphinx Build
============
--
2.13.0
As we now have a document describing the install
requirements for Sphinx, add there the need for GraphViz
and ImageMagick.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
Documentation/doc-guide/sphinx.rst | 13 +++++++++++++
1 file changed, 13 insertions(+)
diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst
index 4c6cb454eaa0..3a41483ed499 100644
--- a/Documentation/doc-guide/sphinx.rst
+++ b/Documentation/doc-guide/sphinx.rst
@@ -68,6 +68,18 @@ the virtual environment before building the documentation.
functionalities required for ``XeLaTex`` to work. For PDF output you'll also
need ``convert(1)`` from ImageMagick (https://www.imagemagick.org).
+Image output
+------------
+
+The kernel documentation build system contains an extension that
+handles images on both GraphViz and SVG formats (see
+:ref:`sphinx_kfigure`).
+
+For it to work, you need to install both GraphViz and ImageMagick
+packages. If those packages are not installed, the build system will
+still build the documentation, but won't include any images at the
+output.
+
Sphinx Build
============
@@ -278,6 +290,7 @@ Rendered as:
- column 3
+.. _sphinx_kfigure:
Figures & Images
================
--
2.13.0
The kfigure module doesn't work with Sphinx version 1.2. So,
update the minimal requirements accordingly.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
Documentation/process/changes.rst | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst
index adbb50ae5246..ceddf1d1e646 100644
--- a/Documentation/process/changes.rst
+++ b/Documentation/process/changes.rst
@@ -53,7 +53,7 @@ mcelog 0.6 mcelog --version
iptables 1.4.2 iptables -V
openssl & libcrypto 1.0.0 openssl version
bc 1.06.95 bc --version
-Sphinx\ [#f1]_ 1.2 sphinx-build --version
+Sphinx\ [#f1]_ 1.3 sphinx-build --version
====================== =============== ========================================
.. [#f1] Sphinx is needed only to build the Kernel documentation
@@ -310,8 +310,8 @@ Sphinx
------
The ReST markups currently used by the Documentation/ files are meant to be
-built with ``Sphinx`` version 1.2 or upper. If you're desiring to build
-PDF outputs, it is recommended to use version 1.4.6.
+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.
.. note::
--
2.13.0
The toolchain used by Sphinx is somewhat complex, and installing
it should be part of the doc-guide.
Move it out of changes.rst.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
Documentation/doc-guide/sphinx.rst | 17 +++++++++++++++++
Documentation/process/changes.rst | 14 ++------------
2 files changed, 19 insertions(+), 12 deletions(-)
diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst
index 84e8e8a9cbdb..1ee109b19322 100644
--- a/Documentation/doc-guide/sphinx.rst
+++ b/Documentation/doc-guide/sphinx.rst
@@ -19,6 +19,23 @@ Finally, there are thousands of plain text documentation files scattered around
``Documentation``. Some of these will likely be converted to reStructuredText
over time, but the bulk of them will remain in plain text.
+.. _sphinx_install:
+
+Sphinx Install
+==============
+
+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.
+
+.. note::
+
+ Please notice that, 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 ``texlive`` packages that provide the minimal set of
+ functionalities required for ``XeLaTex`` to work. For PDF output you'll also
+ need ``convert(1)`` from ImageMagick (https://www.imagemagick.org).
+
Sphinx Build
============
diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst
index ceddf1d1e646..bb2f2fe886f9 100644
--- a/Documentation/process/changes.rst
+++ b/Documentation/process/changes.rst
@@ -309,18 +309,8 @@ Kernel documentation
Sphinx
------
-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.
-
-.. note::
-
- Please notice that, 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 ``texlive`` packages that provide the minimal set of
- functionalities required for ``XeLaTex`` to work. For PDF output you'll also
- need ``convert(1)`` from ImageMagick (https://www.imagemagick.org).
-
+Please see :ref:`sphinx_install` at the doc-guide for details about
+Sphinx requirements.
Getting updated software
========================
--
2.13.0
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 <[email protected]>
---
Documentation/doc-guide/sphinx.rst | 32 ++++++++++++++++++++++++++++++++
1 file changed, 32 insertions(+)
diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst
index 1ee109b19322..3278262164da 100644
--- a/Documentation/doc-guide/sphinx.rst
+++ b/Documentation/doc-guide/sphinx.rst
@@ -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``
--
2.13.0
On Fri, 14 Jul 2017 08:08:19 -0300
Mauro Carvalho Chehab <[email protected]> wrote:
> +Please see :ref:`sphinx_install` at the doc-guide for details about
> +Sphinx requirements.
One small comment here: formatting things this way assumes that people are
reading the documentation in a web browser. Can we replace "at the
doc-guide" with "in Documentation/doc-guide/sphinx.rst" to improve the
usability of the plain-text files?
Otherwise the series looks good to me, thanks.
jon
> Am 14.07.2017 um 17:44 schrieb Jonathan Corbet <[email protected]>:
>
> On Fri, 14 Jul 2017 08:08:19 -0300
> Mauro Carvalho Chehab <[email protected]> wrote:
>
>> +Please see :ref:`sphinx_install` at the doc-guide for details about
>> +Sphinx requirements.
>
> One small comment here: formatting things this way assumes that people are
> reading the documentation in a web browser. Can we replace "at the
> doc-guide" with "in Documentation/doc-guide/sphinx.rst" to improve the
> usability of the plain-text files?
Hm .. I suppose there is a plain text builder for sphinx .. but building
plain-text before reading sources seems not an acceptable option ;)
-- Markus --