[PATCH v2 0/6] Better document Sphinx install instructions

[PATCH v2 0/6] Better document Sphinx install instructions

[Mauro Carvalho Chehab]

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

[PATCH v2 1/6] changes.rst: Update Sphinx minimal requirements

[Mauro Carvalho Chehab]

The kfigure module doesn't work with Sphinx version 1.2. So,
update the minimal requirements accordingly.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 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

[PATCH v2 2/6] docs-rst: move Sphinx install instructions to sphinx.rst

[Mauro Carvalho Chehab]

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 <mchehab@s-opensource.com>
---
 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

[PATCH v2 3/6] sphinx.rst: explain the usage of virtual environment

[Mauro Carvalho Chehab]

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>
---
 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

[PATCH v2 4/6] sphinx.rst: fix unknown reference

[Mauro Carvalho Chehab]

There's no "Sphinx C Domain" reference at the Kernel
documentation. So, don't use references for it.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 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

[PATCH v2 5/6] sphinx.rst: describe the install requirements for kfigure

[Mauro Carvalho Chehab]

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 <mchehab@s-opensource.com>
---
 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

[PATCH v2 6/6] sphinx.rst: better organize the documentation about PDF build

[Mauro Carvalho Chehab]

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 <mchehab@s-opensource.com>
---
 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

Re: [PATCH v2 0/6] Better document Sphinx install instructions

[Jonathan Corbet]

On Fri, 14 Jul 2017 13:41:15 -0300
Mauro Carvalho Chehab <mchehab@s-opensource.com> 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

Re: [PATCH v2 0/6] Better document Sphinx install instructions

[Mauro Carvalho Chehab]

Em Mon, 17 Jul 2017 13:40:51 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> On Fri, 14 Jul 2017 13:41:15 -0300
> Mauro Carvalho Chehab <mchehab@s-opensource.com> 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

Re: [PATCH v2 0/6] Better document Sphinx install instructions

[Jonathan Corbet]

On Mon, 17 Jul 2017 18:23:05 -0300
Mauro Carvalho Chehab <mchehab@s-opensource.com> 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

Re: [PATCH v2 0/6] Better document Sphinx install instructions

[Mauro Carvalho Chehab]

Em Mon, 17 Jul 2017 15:26:33 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> On Mon, 17 Jul 2017 18:23:05 -0300
> Mauro Carvalho Chehab <mchehab@s-opensource.com> 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