Better document Sphinx install instructions
Subsystems (2)
v2 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. 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(-)
Signature · 1 line
2.13.0
PATCH v2 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 v2 2/6 docs-rst: move Sphinx install instructions to sphinx.rst
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` in ``Documentation/doc-guide/sphinx.rst`` +for details about Sphinx requirements. Getting updated software ========================
Signature · 1 line
2.13.0
PATCH v2 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 v2 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 v2 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 v2 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
Quoted 10 lines · On Fri, 14 Jul 2017 13:41:15 -0300 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.rstwith Sphinx install instructions, moving it out ofchanges.rst. and better name patch 2/6.v2: improved the text at
changes.rstto 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:
Quoted 8 lines
Quoted 5 lines · On Fri, 14 Jul 2017 13:41:15 -0300 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.
Quoted 7 lines
Quoted 5 lines
So, add a separate chapter at
sphinx.rstwith Sphinx install instructions, moving it out ofchanges.rst. and better name patch 2/6.v2: improved the text at
changes.rstto 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
Jonathan Corbet
maintainerQuoted 2 lines · On Mon, 17 Jul 2017 18:23:05 -0300 Mauro Carvalho Chehab…
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:
Quoted 8 lines
Quoted 2 lines · On Mon, 17 Jul 2017 18:23:05 -0300 Mauro Carvalho Chehab…
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