Minki/linux
1
0
Fork 1
mirror of https://github.com/torvalds/linux.git synced 2024-11-22 04:02:20 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: Update Sphinx requirements

Browse Source 
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 2021-11-10 18:16:48 +09:00 committed by Jonathan Corbet
parent fa55b7dcdc
commit 6d6a8d6a4e
5 changed files with 29 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
Documentation/doc-guide/sphinx.rst
View File

@ -27,7 +27,7 @@ Sphinx Install
============== ==============
The ReST markups currently used by the Documentation/ files are meant to be 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 There's a script that checks for the Sphinx requirements. Please see
:ref:`sphinx-pre-install` for further details. :ref:`sphinx-pre-install` for further details.
@ -43,10 +43,6 @@ or ``virtualenv``, depending on how your distribution packaged Python 3.
.. note:: .. 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 #) It is recommended to use the RTD theme for html output. Depending
on the Sphinx version, it should be installed separately, on the Sphinx version, it should be installed separately,
with ``pip install sphinx_rtd_theme``. 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 those expressions are written using LaTeX notation. It needs texlive
installed with amsfonts and amsmath in order to evaluate them. 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 $ virtualenv sphinx_2.4.4
$ . sphinx_1.7.9/bin/activate $ . sphinx_2.4.4/bin/activate
(sphinx_1.7.9) $ pip install -r Documentation/sphinx/requirements.txt (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 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 open a new shell, you need to rerun this command to enter again at
the virtual environment before building the documentation. the virtual environment before building the documentation.
@ -81,7 +77,7 @@ output.
PDF and LaTeX builds 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. 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: You should run:
sudo dnf install -y texlive-luatex85 sudo dnf install -y texlive-luatex85
/usr/bin/virtualenv sphinx_1.7.9 /usr/bin/virtualenv sphinx_2.4.4
. sphinx_1.7.9/bin/activate . sphinx_2.4.4/bin/activate
pip install -r Documentation/sphinx/requirements.txt pip install -r Documentation/sphinx/requirements.txt
Can't build as 1 mandatory dependency is missing at ./scripts/sphinx-pre-install line 468. Can't build as 1 mandatory dependency is missing at ./scripts/sphinx-pre-install line 468.

2
Documentation/process/changes.rst
View File

@ -54,7 +54,7 @@ mcelog 0.6 mcelog --version
iptables 1.4.2 iptables -V iptables 1.4.2 iptables -V
openssl & libcrypto 1.0.0 openssl version openssl & libcrypto 1.0.0 openssl version
bc 1.06.95 bc --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 .. [#f1] Sphinx is needed only to build the Kernel documentation

23
Documentation/translations/it_IT/doc-guide/sphinx.rst
View File

@ -35,7 +35,7 @@ Installazione Sphinx
==================== ====================
I marcatori ReST utilizzati nei file in Documentation/ sono pensati per essere 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 Esiste uno script che verifica i requisiti Sphinx. Per ulteriori dettagli
consultate :ref:`it_sphinx-pre-install`. consultate :ref:`it_sphinx-pre-install`.
@ -53,11 +53,6 @@ pacchettizzato dalla vostra distribuzione.
.. note:: .. 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. #) Viene raccomandato l'uso del tema RTD per la documentazione in HTML.
A seconda della versione di Sphinx, potrebbe essere necessaria A seconda della versione di Sphinx, potrebbe essere necessaria
l'installazione tramite il comando ``pip install sphinx_rtd_theme``. 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 utilizzando LaTeX. Per una corretta interpretazione, è necessario aver
installato texlive con i pacchetti amdfonts e amsmath. 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 $ virtualenv sphinx_2.4.4
$ . sphinx_1.7.9/bin/activate $ . sphinx_2.4.4/bin/activate
(sphinx_1.7.9) $ pip install -r Documentation/sphinx/requirements.txt (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, indicare che state usando il nuovo ambiente. Se aprite un nuova sessione,
prima di generare la documentazione, dovrete rieseguire questo comando per prima di generare la documentazione, dovrete rieseguire questo comando per
rientrare nell'ambiente virtuale. rientrare nell'ambiente virtuale.
@ -94,7 +89,7 @@ Generazione in PDF e LaTeX
-------------------------- --------------------------
Al momento, la generazione di questi documenti è supportata solo dalle 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 Per la generazione di PDF e LaTeX, avrete bisogno anche del pacchetto
``XeLaTeX`` nella versione 3.14159265 ``XeLaTeX`` nella versione 3.14159265
@ -119,8 +114,8 @@ l'installazione::
You should run: You should run:
sudo dnf install -y texlive-luatex85 sudo dnf install -y texlive-luatex85
/usr/bin/virtualenv sphinx_1.7.9 /usr/bin/virtualenv sphinx_2.4.4
. sphinx_1.7.9/bin/activate . sphinx_2.4.4/bin/activate
pip install -r Documentation/sphinx/requirements.txt pip install -r Documentation/sphinx/requirements.txt
Can't build as 1 mandatory dependency is missing at ./scripts/sphinx-pre-install line 468. Can't build as 1 mandatory dependency is missing at ./scripts/sphinx-pre-install line 468.

2
Documentation/translations/it_IT/process/changes.rst
View File

@ -57,7 +57,7 @@ mcelog 0.6 mcelog --version
iptables 1.4.2 iptables -V iptables 1.4.2 iptables -V
openssl & libcrypto 1.0.0 openssl version openssl & libcrypto 1.0.0 openssl version
bc 1.06.95 bc --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 .. [#f1] Sphinx è necessario solo per produrre la documentazione del Kernel

21
Documentation/translations/zh_CN/doc-guide/sphinx.rst
View File

@ -26,7 +26,7 @@ reStructuredText文件可能包含包含来自源文件的结构化文档注释
安装Sphinx 安装Sphinx
========== ==========
Documentation/ 下的ReST文件现在使用sphinx1.3或更高版本构建。 Documentation/ 下的ReST文件现在使用sphinx1.7或更高版本构建。
这有一个脚本可以检查Sphinx的依赖项。更多详细信息见 这有一个脚本可以检查Sphinx的依赖项。更多详细信息见
:ref:`sphinx-pre-install_zh` 。 :ref:`sphinx-pre-install_zh` 。
@ -40,22 +40,19 @@ Documentation/ 下的ReST文件现在使用sphinx1.3或更高版本构建。
.. note:: .. note::
#) 低于1.5版本的Sphinx无法与Python的0.13.1或更高版本docutils一起正常工作。
如果您想使用这些版本，那么应该运行 ``pip install 'docutils==0.12'`` 。
#) html输出建议使用RTD主题。根据Sphinx版本的不同，它应该用 #) html输出建议使用RTD主题。根据Sphinx版本的不同，它应该用
``pip install sphinx_rtd_theme`` 单独安装。 ``pip install sphinx_rtd_theme`` 单独安装。
#) 一些ReST页面包含数学表达式。由于Sphinx的工作方式，这些表达式是使用 LaTeX #) 一些ReST页面包含数学表达式。由于Sphinx的工作方式，这些表达式是使用 LaTeX
编写的。它需要安装amsfonts和amsmath宏包，以便显示。 编写的。它需要安装amsfonts和amsmath宏包，以便显示。
总之，如您要安装Sphinx 1.7.9版本，应执行:: 总之，如您要安装Sphinx 2.4.4版本，应执行::
$ virtualenv sphinx_1.7.9 $ virtualenv sphinx_2.4.4
$ . sphinx_1.7.9/bin/activate $ . sphinx_2.4.4/bin/activate
(sphinx_1.7.9) $ pip install -r Documentation/sphinx/requirements.txt (sphinx_2.4.4) $ pip install -r Documentation/sphinx/requirements.txt
在运行 ``. sphinx_1.7.9/bin/activate`` 之后，提示符将变化，以指示您正在使用新 在运行 ``. sphinx_2.4.4/bin/activate`` 之后，提示符将变化，以指示您正在使用新
环境。如果您打开了一个新的shell，那么在构建文档之前，您需要重新运行此命令以再 环境。如果您打开了一个新的shell，那么在构建文档之前，您需要重新运行此命令以再
次进入虚拟环境中。 次进入虚拟环境中。
@ -71,7 +68,7 @@ Documentation/ 下的ReST文件现在使用sphinx1.3或更高版本构建。
PDF和LaTeX构建 PDF和LaTeX构建
-------------- --------------
目前只有Sphinx 1.4及更高版本才支持这种构建。 目前只有Sphinx 2.4及更高版本才支持这种构建。
对于PDF和LaTeX输出，还需要 ``XeLaTeX`` 3.14159265版本。（译注：此版本号真实 对于PDF和LaTeX输出，还需要 ``XeLaTeX`` 3.14159265版本。（译注：此版本号真实
存在） 存在）
@ -93,8 +90,8 @@ PDF和LaTeX构建
You should run: You should run:
sudo dnf install -y texlive-luatex85 sudo dnf install -y texlive-luatex85
/usr/bin/virtualenv sphinx_1.7.9 /usr/bin/virtualenv sphinx_2.4.4
. sphinx_1.7.9/bin/activate . sphinx_2.4.4/bin/activate
pip install -r Documentation/sphinx/requirements.txt pip install -r Documentation/sphinx/requirements.txt
Can't build as 1 mandatory dependency is missing at ./scripts/sphinx-pre-install line 468. Can't build as 1 mandatory dependency is missing at ./scripts/sphinx-pre-install line 468.