Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.kernel > #1687256 > unrolled thread

[PATCH 0/6] Better document Sphinx install instructions

Back to article view | Back to linux.kernel

Contents

  [PATCH 0/6] Better document Sphinx install instructions Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-07-14 13:10 +0200
    [PATCH 3/6] sphinx.rst: explain the usage of virtual environment Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-07-14 13:10 +0200
    [PATCH 2/6] docs-rst: update Sphinx install instructions Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-07-14 13:10 +0200
      Re: [PATCH 2/6] docs-rst: update Sphinx install instructions Jonathan Corbet <corbet@lwn.net> - 2017-07-14 17:50 +0200
        Re: [PATCH 2/6] docs-rst: update Sphinx install instructions Markus Heiser <markus.heiser@darmarit.de> - 2017-07-14 18:20 +0200
    [PATCH 1/6] changes.rst: Update Sphinx minimal requirements Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-07-14 13:10 +0200

#1687256 — [PATCH 0/6] Better document Sphinx install instructions

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

[toc] | [next] | [standalone]

#1687258 — [PATCH 3/6] 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>
---
 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

[toc] | [prev] | [next] | [standalone]

#1687259 — [PATCH 2/6] docs-rst: update Sphinx install instructions

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

[toc] | [prev] | [next] | [standalone]

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

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

[toc] | [prev] | [next] | [standalone]

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

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

[toc] | [prev] | [next] | [standalone]

#1687262 — [PATCH 1/6] changes.rst: Update Sphinx minimal requirements

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

[toc] | [prev] | [standalone]

Back to top | Article view | linux.kernel

csiph-web