mirror of
https://github.com/torvalds/linux.git
synced 2024-11-21 19:41:42 +00:00
docs: Update Sphinx requirements
Commit f546ff0c0c ("Move our minimum Sphinx version to 1.7") raised
the minimum version to 1.7.
For pdfdocs, sphinx_pre_install says:
note: If you want pdf, you need at least Sphinx 2.4.4.
, and current requirements.txt installs Sphinx 2.4.4.
Update Sphinx versions mentioned in docs and remove a note on earlier
Sphinx versions.
Update zh_CN and it_IT translations as well.
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Cc: Federico Vaga <federico.vaga@vaga.pv.it>
Cc: Alex Shi <alexs@kernel.org>
Reviewed-by: Alex Shi <alexs@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This commit is contained in:
Akira Yokosawa
Jonathan Corbet
parent
fa55b7dcdc
commit
6d6a8d6a4e
@ -27,7 +27,7 @@ Sphinx Install
|
||||
==============
|
||||
|
||||
The ReST markups currently used by the Documentation/ files are meant to be
|
||||
built with ``Sphinx`` version 1.3 or higher.
|
||||
built with ``Sphinx`` version 1.7 or higher.
|
||||
|
||||
There's a script that checks for the Sphinx requirements. Please see
|
||||
:ref:`sphinx-pre-install` for further details.
|
||||
@ -43,10 +43,6 @@ 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 higher. 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 separately,
|
||||
with ``pip install sphinx_rtd_theme``.
|
||||
@ -55,13 +51,13 @@ or ``virtualenv``, depending on how your distribution packaged Python 3.
|
||||
those expressions are written using LaTeX notation. It needs texlive
|
||||
installed with amsfonts and amsmath in order to evaluate them.
|
||||
|
||||
In summary, if you want to install Sphinx version 1.7.9, you should do::
|
||||
In summary, if you want to install Sphinx version 2.4.4, you should do::
|
||||
|
||||
$ virtualenv sphinx_1.7.9
|
||||
$ . sphinx_1.7.9/bin/activate
|
||||
(sphinx_1.7.9) $ pip install -r Documentation/sphinx/requirements.txt
|
||||
$ virtualenv sphinx_2.4.4
|
||||
$ . sphinx_2.4.4/bin/activate
|
||||
(sphinx_2.4.4) $ pip install -r Documentation/sphinx/requirements.txt
|
||||
|
||||
After running ``. sphinx_1.7.9/bin/activate``, the prompt will change,
|
||||
After running ``. sphinx_2.4.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.
|
||||
@ -81,7 +77,7 @@ output.
|
||||
PDF and LaTeX builds
|
||||
--------------------
|
||||
|
||||
Such builds are currently supported only with Sphinx versions 1.4 and higher.
|
||||
Such builds are currently supported only with Sphinx versions 2.4 and higher.
|
||||
|
||||
For PDF and LaTeX output, you'll also need ``XeLaTeX`` version 3.14159265.
|
||||
|
||||
@ -104,8 +100,8 @@ command line options for your distro::
|
||||
You should run:
|
||||
|
||||
sudo dnf install -y texlive-luatex85
|
||||
/usr/bin/virtualenv sphinx_1.7.9
|
||||
. sphinx_1.7.9/bin/activate
|
||||
/usr/bin/virtualenv sphinx_2.4.4
|
||||
. sphinx_2.4.4/bin/activate
|
||||
pip install -r Documentation/sphinx/requirements.txt
|
||||
|
||||
Can't build as 1 mandatory dependency is missing at ./scripts/sphinx-pre-install line 468.
|
||||
|
||||
@ -54,7 +54,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.3 sphinx-build --version
|
||||
Sphinx\ [#f1]_ 1.7 sphinx-build --version
|
||||
====================== =============== ========================================
|
||||
|
||||
.. [#f1] Sphinx is needed only to build the Kernel documentation
|
||||
|
||||
@ -35,7 +35,7 @@ Installazione Sphinx
|
||||
====================
|
||||
|
||||
I marcatori ReST utilizzati nei file in Documentation/ sono pensati per essere
|
||||
processati da ``Sphinx`` nella versione 1.3 o superiore.
|
||||
processati da ``Sphinx`` nella versione 1.7 o superiore.
|
||||
|
||||
Esiste uno script che verifica i requisiti Sphinx. Per ulteriori dettagli
|
||||
consultate :ref:`it_sphinx-pre-install`.
|
||||
@ -53,11 +53,6 @@ pacchettizzato dalla vostra distribuzione.
|
||||
|
||||
.. note::
|
||||
|
||||
#) Le versioni di Sphinx inferiori alla 1.5 non funzionano bene
|
||||
con il pacchetto Python docutils versione 0.13.1 o superiore.
|
||||
Se volete usare queste versioni, allora dovere eseguire
|
||||
``pip install 'docutils==0.12'``.
|
||||
|
||||
#) Viene raccomandato l'uso del tema RTD per la documentazione in HTML.
|
||||
A seconda della versione di Sphinx, potrebbe essere necessaria
|
||||
l'installazione tramite il comando ``pip install sphinx_rtd_theme``.
|
||||
@ -67,13 +62,13 @@ pacchettizzato dalla vostra distribuzione.
|
||||
utilizzando LaTeX. Per una corretta interpretazione, è necessario aver
|
||||
installato texlive con i pacchetti amdfonts e amsmath.
|
||||
|
||||
Riassumendo, se volete installare la versione 1.7.9 di Sphinx dovete eseguire::
|
||||
Riassumendo, se volete installare la versione 2.4.4 di Sphinx dovete eseguire::
|
||||
|
||||
$ virtualenv sphinx_1.7.9
|
||||
$ . sphinx_1.7.9/bin/activate
|
||||
(sphinx_1.7.9) $ pip install -r Documentation/sphinx/requirements.txt
|
||||
$ virtualenv sphinx_2.4.4
|
||||
$ . sphinx_2.4.4/bin/activate
|
||||
(sphinx_2.4.4) $ pip install -r Documentation/sphinx/requirements.txt
|
||||
|
||||
Dopo aver eseguito ``. sphinx_1.7.9/bin/activate``, il prompt cambierà per
|
||||
Dopo aver eseguito ``. sphinx_2.4.4/bin/activate``, il prompt cambierà per
|
||||
indicare che state usando il nuovo ambiente. Se aprite un nuova sessione,
|
||||
prima di generare la documentazione, dovrete rieseguire questo comando per
|
||||
rientrare nell'ambiente virtuale.
|
||||
@ -94,7 +89,7 @@ Generazione in PDF e LaTeX
|
||||
--------------------------
|
||||
|
||||
Al momento, la generazione di questi documenti è supportata solo dalle
|
||||
versioni di Sphinx superiori alla 1.4.
|
||||
versioni di Sphinx superiori alla 2.4.
|
||||
|
||||
Per la generazione di PDF e LaTeX, avrete bisogno anche del pacchetto
|
||||
``XeLaTeX`` nella versione 3.14159265
|
||||
@ -119,8 +114,8 @@ l'installazione::
|
||||
You should run:
|
||||
|
||||
sudo dnf install -y texlive-luatex85
|
||||
/usr/bin/virtualenv sphinx_1.7.9
|
||||
. sphinx_1.7.9/bin/activate
|
||||
/usr/bin/virtualenv sphinx_2.4.4
|
||||
. sphinx_2.4.4/bin/activate
|
||||
pip install -r Documentation/sphinx/requirements.txt
|
||||
|
||||
Can't build as 1 mandatory dependency is missing at ./scripts/sphinx-pre-install line 468.
|
||||
|
||||
@ -57,7 +57,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.3 sphinx-build --version
|
||||
Sphinx\ [#f1]_ 1.7 sphinx-build --version
|
||||
====================== ================= ========================================
|
||||
|
||||
.. [#f1] Sphinx è necessario solo per produrre la documentazione del Kernel
|
||||
|
||||
@ -26,7 +26,7 @@ reStructuredText文件可能包含包含来自源文件的结构化文档注释
|
||||
安装Sphinx
|
||||
==========
|
||||
|
||||
Documentation/ 下的ReST文件现在使用sphinx1.3或更高版本构建。
|
||||
Documentation/ 下的ReST文件现在使用sphinx1.7或更高版本构建。
|
||||
|
||||
这有一个脚本可以检查Sphinx的依赖项。更多详细信息见
|
||||
:ref:`sphinx-pre-install_zh` 。
|
||||
@ -40,22 +40,19 @@ Documentation/ 下的ReST文件现在使用sphinx1.3或更高版本构建。
|
||||
|
||||
.. note::
|
||||
|
||||
#) 低于1.5版本的Sphinx无法与Python的0.13.1或更高版本docutils一起正常工作。
|
||||
如果您想使用这些版本，那么应该运行 ``pip install 'docutils==0.12'`` 。
|
||||
|
||||
#) html输出建议使用RTD主题。根据Sphinx版本的不同，它应该用
|
||||
``pip install sphinx_rtd_theme`` 单独安装。
|
||||
|
||||
#) 一些ReST页面包含数学表达式。由于Sphinx的工作方式，这些表达式是使用 LaTeX
|
||||
编写的。它需要安装amsfonts和amsmath宏包，以便显示。
|
||||
|
||||
总之，如您要安装Sphinx 1.7.9版本，应执行::
|
||||
总之，如您要安装Sphinx 2.4.4版本，应执行::
|
||||
|
||||
$ virtualenv sphinx_1.7.9
|
||||
$ . sphinx_1.7.9/bin/activate
|
||||
(sphinx_1.7.9) $ pip install -r Documentation/sphinx/requirements.txt
|
||||
$ virtualenv sphinx_2.4.4
|
||||
$ . sphinx_2.4.4/bin/activate
|
||||
(sphinx_2.4.4) $ pip install -r Documentation/sphinx/requirements.txt
|
||||
|
||||
在运行 ``. sphinx_1.7.9/bin/activate`` 之后，提示符将变化，以指示您正在使用新
|
||||
在运行 ``. sphinx_2.4.4/bin/activate`` 之后，提示符将变化，以指示您正在使用新
|
||||
环境。如果您打开了一个新的shell，那么在构建文档之前，您需要重新运行此命令以再
|
||||
次进入虚拟环境中。
|
||||
|
||||
@ -71,7 +68,7 @@ Documentation/ 下的ReST文件现在使用sphinx1.3或更高版本构建。
|
||||
PDF和LaTeX构建
|
||||
--------------
|
||||
|
||||
目前只有Sphinx 1.4及更高版本才支持这种构建。
|
||||
目前只有Sphinx 2.4及更高版本才支持这种构建。
|
||||
|
||||
对于PDF和LaTeX输出，还需要 ``XeLaTeX`` 3.14159265版本。（译注：此版本号真实
|
||||
存在）
|
||||
@ -93,8 +90,8 @@ PDF和LaTeX构建
|
||||
You should run:
|
||||
|
||||
sudo dnf install -y texlive-luatex85
|
||||
/usr/bin/virtualenv sphinx_1.7.9
|
||||
. sphinx_1.7.9/bin/activate
|
||||
/usr/bin/virtualenv sphinx_2.4.4
|
||||
. sphinx_2.4.4/bin/activate
|
||||
pip install -r Documentation/sphinx/requirements.txt
|
||||
|
||||
Can't build as 1 mandatory dependency is missing at ./scripts/sphinx-pre-install line 468.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user