Better document Sphinx install instructions
Subsystems (2)
cover 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(-)
Signature · 1 line
2.13.0
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.
--- Documentation/process/changes.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)
Documentation/process/changes.rst +3 -3
@@ -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::
Signature · 1 line
2.13.0
PATCH 2/6 docs-rst: update Sphinx install instructions
In reply to Mauro Carvalho ChehabThe toolchain used by Sphinx is somewhat complex, and installing it should be part of the doc-guide.
Move it out of changes.rst.
--- Documentation/doc-guide/sphinx.rst | 17 +++++++++++++++++ Documentation/process/changes.rst | 14 ++------------ 2 files changed, 19 insertions(+), 12 deletions(-)
Documentation/doc-guide/sphinx.rst +17 -0
@@ -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 ============
Documentation/process/changes.rst +2 -12
@@ -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 ========================
Signature · 1 line
2.13.0
Jonathan Corbet
maintainerRe: [PATCH 2/6] docs-rst: update Sphinx install instructions
Documentation/process/changes.rst Kernel documentation · line 313
Quoted 2 lines · On Fri, 14 Jul 2017 08:08:19 -0300 Mauro Carvalho Chehab…
Documentation/process/changes.rst +2
-0+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
Quoted 6 lines
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:
Quoted 7 lines
Documentation/process/changes.rst Kernel documentation · line 313
Quoted 2 lines
Documentation/process/changes.rst +2
-0+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 --
PATCH 3/6 sphinx.rst: explain the usage of virtual environment
In reply to Mauro Carvalho ChehabAs the Sphinx build seems very fragile, specially for PDF output, add a notice about how to use it on a virtual environment.
--- Documentation/doc-guide/sphinx.rst | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+)
Documentation/doc-guide/sphinx.rst +32 -0
@@ -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``
Signature · 1 line
2.13.0
PATCH 4/6 sphinx.rst: fix unknown reference
In reply to Mauro Carvalho ChehabThere's no "Sphinx C Domain" reference at the Kernel documentation. So, don't use references for it.
--- Documentation/doc-guide/sphinx.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/doc-guide/sphinx.rst +1 -1
@@ -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
Signature · 1 line
2.13.0
PATCH 5/6 sphinx.rst: describe the install requirements for kfigure
In reply to Mauro Carvalho ChehabAs we now have a document describing the install requirements for Sphinx, add there the need for GraphViz and ImageMagick.
--- Documentation/doc-guide/sphinx.rst | 13 +++++++++++++ 1 file changed, 13 insertions(+)
Documentation/doc-guide/sphinx.rst +13 -0
@@ -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 ================
Signature · 1 line
2.13.0
PATCH 6/6 sphinx.rst: better organize the documentation about PDF build
In reply to Mauro Carvalho ChehabInstead 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.
--- Documentation/doc-guide/sphinx.rst | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-)
Documentation/doc-guide/sphinx.rst +13 -8
@@ -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 ============
Signature · 1 line
2.13.0