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. and better name patch 2/6.
v2: improved the text at changes.rst to point to the file name with the
Sphinx build instructions.
Mauro Carvalho Chehab (6):
changes.rst: Update Sphinx minimal requirements
docs-rst: move Sphinx install instructions to sphinx.rst
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
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
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..560beaef5a7c 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` in ``Documentation/doc-guide/sphinx.rst``
+for details about Sphinx requirements.
Getting updated software
========================
--
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
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
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
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
On Fri, 14 Jul 2017 13:41:15 -0300
Mauro Carvalho Chehab <[email protected]> wrote:
> 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. and better name patch 2/6.
>
> v2: improved the text at changes.rst to point to the file name with the
> Sphinx build instructions.
I've applied this set, thanks.
jon
Em Mon, 17 Jul 2017 13:40:51 -0600
Jonathan Corbet <[email protected]> escreveu:
> On Fri, 14 Jul 2017 13:41:15 -0300
> Mauro Carvalho Chehab <[email protected]> wrote:
>
> > 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. and better name patch 2/6.
> >
> > v2: improved the text at changes.rst to point to the file name with the
> > Sphinx build instructions.
>
> I've applied this set, thanks.
Thanks!
Btw, I'm submitting in a few a second version of the patches with
add a script to check Sphinx dependencies.
Thanks,
Mauro
On Mon, 17 Jul 2017 18:23:05 -0300
Mauro Carvalho Chehab <[email protected]> wrote:
> Btw, I'm submitting in a few a second version of the patches with
> add a script to check Sphinx dependencies.
I figured I wasn't going to look at that until you get up to v42 or so -
maybe another day or two...? :)
jon
Em Mon, 17 Jul 2017 15:26:33 -0600
Jonathan Corbet <[email protected]> escreveu:
> On Mon, 17 Jul 2017 18:23:05 -0300
> Mauro Carvalho Chehab <[email protected]> wrote:
>
> > Btw, I'm submitting in a few a second version of the patches with
> > add a script to check Sphinx dependencies.
>
> I figured I wasn't going to look at that until you get up to v42 or so -
> maybe another day or two...? :)
Just sent ;)
There are two patches that I didn't send via e-mail:
https://git.linuxtv.org/mchehab/experimental.git/commit/?h=sphinx_install_v2&id=4bd9e1ea9ddabce144ee4c84549449563f0b8416
https://git.linuxtv.org/mchehab/experimental.git/commit/?h=sphinx_install_v2&id=6b9596e432709f7a7def85873c8ccbb837fdf4a2
The problem is that SVG files often have lines bigger than 998 chars,
with is the limit that e-mails usually accept (and VGER enforces).
We need some sort of script to break long lines. I remember that I
wrote one once, but need to seek for it, as it is not at the
usual places.
Those two patches are required for PDF build to work without errors
on Ubuntu 17.04. The problem there is that ImageMagick is a way
more pedantic there than on other distros, and don't support
several atributes that inkscape add. I had to use some tools to
filter out those arguments (svgo, scour) and even manually replace
font-family there, for it to properly recognize the SVG contents.
What's funny is that ImageMagick version on Ubuntu is newer
than the one in Fedora 26:
ubuntu17.04$ dpkg -l imagemagick
Desired=Unknown/Install/Remove/Purge/Hold
| Status=Not/Inst/Conf-files/Unpacked/halF-conf/Half-inst/trig-aWait/Trig-pend
|/ Err?=(none)/Reinst-required (Status,Err: uppercase=bad)
||/ Name Version Architecture Description
+++-=======================-================-================-====================================================
ii imagemagick 8:6.9.7.4+dfsg-3 amd64 image manipulation programs -- binaries
fedora25$ rpm -q ImageMagick
ImageMagick-6.9.3.0-6.fc25.x86_64
fedora26$ rpm -q ImageMagick
ImageMagick-6.9.3.0-6.fc26.x86_64
Perhaps some regression?
Thanks,
Mauro