[PATCH] docs: Update Sphinx requirements

[PATCH] docs: Update Sphinx requirements

[Akira Yokosawa]

Subject: [PATCH] docs: Update Sphinx requirements

Commit f546ff0c0c07 ("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>
---
 Documentation/doc-guide/sphinx.rst            | 22 ++++++++----------
 Documentation/process/changes.rst             |  2 +-
 .../translations/it_IT/doc-guide/sphinx.rst   | 23 ++++++++-----------
 .../translations/it_IT/process/changes.rst    |  2 +-
 .../translations/zh_CN/doc-guide/sphinx.rst   | 21 ++++++++---------
 5 files changed, 29 insertions(+), 41 deletions(-)

diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst
index ec3e71f56009..e445cb146efe 100644
--- a/Documentation/doc-guide/sphinx.rst
+++ b/Documentation/doc-guide/sphinx.rst
@@ -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.
diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst
index e35ab74a0f80..b398b8576417 100644
--- a/Documentation/process/changes.rst
+++ b/Documentation/process/changes.rst
@@ -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
diff --git a/Documentation/translations/it_IT/doc-guide/sphinx.rst b/Documentation/translations/it_IT/doc-guide/sphinx.rst
index 0046d75d9a70..9762452c584c 100644
--- a/Documentation/translations/it_IT/doc-guide/sphinx.rst
+++ b/Documentation/translations/it_IT/doc-guide/sphinx.rst
@@ -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.
diff --git a/Documentation/translations/it_IT/process/changes.rst b/Documentation/translations/it_IT/process/changes.rst
index 87d081889bfc..dc7193377b7f 100644
--- a/Documentation/translations/it_IT/process/changes.rst
+++ b/Documentation/translations/it_IT/process/changes.rst
@@ -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
diff --git a/Documentation/translations/zh_CN/doc-guide/sphinx.rst b/Documentation/translations/zh_CN/doc-guide/sphinx.rst
index 951595c7d599..23eac67fbc30 100644
--- a/Documentation/translations/zh_CN/doc-guide/sphinx.rst
+++ b/Documentation/translations/zh_CN/doc-guide/sphinx.rst
@@ -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.

base-commit: 603bdf5d6c092eb05666decd84288dfda71eee90
-- 
2.17.1

Re: [PATCH] docs: Update Sphinx requirements

[Alex Shi]

On Wed, Nov 10, 2021 at 5:16 PM Akira Yokosawa <akiyks@gmail.com> wrote:
>
> Subject: [PATCH] docs: Update Sphinx requirements
>
> Commit f546ff0c0c07 ("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>

Reviewed-by: Alex Shi <alexs@kernel.org>

> Cc: Federico Vaga <federico.vaga@vaga.pv.it>
> Cc: Alex Shi <alexs@kernel.org>
> ---
>  Documentation/doc-guide/sphinx.rst            | 22 ++++++++----------
>  Documentation/process/changes.rst             |  2 +-
>  .../translations/it_IT/doc-guide/sphinx.rst   | 23 ++++++++-----------
>  .../translations/it_IT/process/changes.rst    |  2 +-
>  .../translations/zh_CN/doc-guide/sphinx.rst   | 21 ++++++++---------
>  5 files changed, 29 insertions(+), 41 deletions(-)
>
> diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst
> index ec3e71f56009..e445cb146efe 100644
> --- a/Documentation/doc-guide/sphinx.rst
> +++ b/Documentation/doc-guide/sphinx.rst
> @@ -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.
> diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst
> index e35ab74a0f80..b398b8576417 100644
> --- a/Documentation/process/changes.rst
> +++ b/Documentation/process/changes.rst
> @@ -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
> diff --git a/Documentation/translations/it_IT/doc-guide/sphinx.rst b/Documentation/translations/it_IT/doc-guide/sphinx.rst
> index 0046d75d9a70..9762452c584c 100644
> --- a/Documentation/translations/it_IT/doc-guide/sphinx.rst
> +++ b/Documentation/translations/it_IT/doc-guide/sphinx.rst
> @@ -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.
> diff --git a/Documentation/translations/it_IT/process/changes.rst b/Documentation/translations/it_IT/process/changes.rst
> index 87d081889bfc..dc7193377b7f 100644
> --- a/Documentation/translations/it_IT/process/changes.rst
> +++ b/Documentation/translations/it_IT/process/changes.rst
> @@ -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
> diff --git a/Documentation/translations/zh_CN/doc-guide/sphinx.rst b/Documentation/translations/zh_CN/doc-guide/sphinx.rst
> index 951595c7d599..23eac67fbc30 100644
> --- a/Documentation/translations/zh_CN/doc-guide/sphinx.rst
> +++ b/Documentation/translations/zh_CN/doc-guide/sphinx.rst
> @@ -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.
>
> base-commit: 603bdf5d6c092eb05666decd84288dfda71eee90
> --
> 2.17.1
>
>

Re: [PATCH] docs: Update Sphinx requirements

[Jonathan Corbet]

Akira Yokosawa <akiyks@gmail.com> writes:

> Subject: [PATCH] docs: Update Sphinx requirements
>
> Commit f546ff0c0c07 ("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.

It may be time to consider raising the minimum sphinx version
overall...  meanwhile, though, I've applied this, thanks.

jon

Re: [PATCH] docs: Update Sphinx requirements

[Akira Yokosawa]

On Mon, 15 Nov 2021 02:48:19 -0700
Jonathan Corbet wrote:
> Akira Yokosawa <akiyks@gmail.com> writes:
> 
>> Subject: [PATCH] docs: Update Sphinx requirements
>>
>> Commit f546ff0c0c07 ("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.
> 
> It may be time to consider raising the minimum sphinx version
> overall...

There is one thing we need to address (you might well be aware of).

Our Documentation/conf.py is not compatible for hrmldocs with
the combination sphinx_rtd_theme 1.0.0 and Sphinx >= 3.0.
This issue is the same as the one reported at:
    https://github.com/readthedocs/sphinx_rtd_theme/issues/1240
    "No stylesheet after upgrading to 1.0.0"

I tried the fix suggested there (html_css_files option),
and a stylesheet can be generated.
But the resulting html pages look quite different from the one
you see at https://www.kernel.org/doc/html/latest/ with the sans
font for text and distracting look of monospaced strings.

You can see a screenshot of such a page at
    https://fars.ee/nkkZ

I guess there should be some knobs of Sphinx for customizing
the style, but have not figured them out.

Thoughts?

        Thanks, Akira

>              meanwhile, though, I've applied this, thanks. 
> 
> jon
> 

Re: [PATCH] docs: Update Sphinx requirements

[Akira Yokosawa]

On Tue, 16 Nov 2021 10:37:31 +0900
Akira Yokosawa wrote:
> On Mon, 15 Nov 2021 02:48:19 -0700
> Jonathan Corbet wrote:
>> Akira Yokosawa <akiyks@gmail.com> writes:
>>
>>> Subject: [PATCH] docs: Update Sphinx requirements
>>>
>>> Commit f546ff0c0c07 ("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.
>>
>> It may be time to consider raising the minimum sphinx version
>> overall...
> 
> There is one thing we need to address (you might well be aware of).
> 
> Our Documentation/conf.py is not compatible for hrmldocs with
> the combination sphinx_rtd_theme 1.0.0 and Sphinx >= 3.0.
> This issue is the same as the one reported at:
>     https://github.com/readthedocs/sphinx_rtd_theme/issues/1240
>     "No stylesheet after upgrading to 1.0.0"
> 
> I tried the fix suggested there (html_css_files option),
> and a stylesheet can be generated.
> But the resulting html pages look quite different from the one
> you see at https://www.kernel.org/doc/html/latest/ with the sans
> font for text and distracting look of monospaced strings.
> 
> You can see a screenshot of such a page at
>     https://fars.ee/nkkZ

Having looked at https://sphinx-themes.org/sample-sites/sphinx-rtd-theme/,
I'm wondering if the screenshot above is exactly what you'd
expect by using the theme in the first place.

Hmm??

        Thanks, Akira

> 
> I guess there should be some knobs of Sphinx for customizing
> the style, but have not figured them out.
> 
> Thoughts?
> 
>         Thanks, Akira
> 
>>              meanwhile, though, I've applied this, thanks. 
>>
>> jon
>>