[PATCH 0/6] Better document Sphinx install instructions

[PATCH 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.

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

[PATCH 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 2/6] docs-rst: update Sphinx install instructions

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

[PATCH 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 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 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 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 2/6] docs-rst: update Sphinx install instructions

[Jonathan Corbet]

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

Re: [PATCH 2/6] docs-rst: update Sphinx install instructions

[Markus Heiser]

> Am 14.07.2017 um 17:44 schrieb Jonathan Corbet <corbet@lwn.net>:
> 
> On Fri, 14 Jul 2017 08:08:19 -0300
> Mauro Carvalho Chehab <mchehab@s-opensource.com> 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 --