As discussed (see Links), there is some inertia to move to the recent
Sphinx versions for the doc build environment.
As first step, drop the version constraints and the related comments.
Then, the sphinx-pre-install script will fail though with:
Can't get default sphinx version from ./Documentation/sphinx/requirements.txt at ./scripts/sphinx-pre-install line 305.
The script simply expects to parse a version constraint with Sphinx in the
requirements.txt. That version is used in the script for suggesting the
virtualenv directory name.
To suggest a virtualenv directory name, when there is no version given in
the requirements.txt, one could try to guess the version that would be
downloaded with 'pip install -r Documentation/sphinx/requirements.txt'.
However, there seems no simple way to get that version without actually
setting up the venv and running pip. So, instead, name the directory with
the fixed name 'sphinx_latest'.
Finally update the Sphinx build documentation to reflect this directory
name change.
Link: https://lore.kernel.org/linux-doc/[email protected]/
Link: https://lore.kernel.org/linux-doc/[email protected]/
Signed-off-by: Lukas Bulwahn <[email protected]>
---
Documentation/doc-guide/sphinx.rst | 11 ++++++-----
Documentation/sphinx/requirements.txt | 8 +++-----
scripts/sphinx-pre-install | 19 +++----------------
3 files changed, 12 insertions(+), 26 deletions(-)
diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst
index 709e19821a16..8081ebfe48bc 100644
--- a/Documentation/doc-guide/sphinx.rst
+++ b/Documentation/doc-guide/sphinx.rst
@@ -48,13 +48,14 @@ or ``virtualenv``, depending on how your distribution packaged Python 3.
on the Sphinx version, it should be installed separately,
with ``pip install sphinx_rtd_theme``.
-In summary, if you want to install Sphinx version 2.4.4, you should do::
+In summary, if you want to install the latest version of Sphinx, you
+should do::
- $ virtualenv sphinx_2.4.4
- $ . sphinx_2.4.4/bin/activate
- (sphinx_2.4.4) $ pip install -r Documentation/sphinx/requirements.txt
+ $ virtualenv sphinx_latest
+ $ . sphinx_latest/bin/activate
+ (sphinx_latest) $ pip install -r Documentation/sphinx/requirements.txt
-After running ``. sphinx_2.4.4/bin/activate``, the prompt will change,
+After running ``. sphinx_latest/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.
diff --git a/Documentation/sphinx/requirements.txt b/Documentation/sphinx/requirements.txt
index 5d47ed443949..1f3b98eee2c9 100644
--- a/Documentation/sphinx/requirements.txt
+++ b/Documentation/sphinx/requirements.txt
@@ -1,6 +1,4 @@
-# jinja2>=3.1 is not compatible with Sphinx<4.0
-jinja2<3.1
-# alabaster>=0.7.14 is not compatible with Sphinx<=3.3
-alabaster<0.7.14
-Sphinx==2.4.4
+jinja2
+alabaster
+Sphinx
pyyaml
diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install
index de0de5dd676e..4c781617ffe6 100755
--- a/scripts/sphinx-pre-install
+++ b/scripts/sphinx-pre-install
@@ -280,8 +280,6 @@ sub get_sphinx_version($)
sub check_sphinx()
{
- my $default_version;
-
open IN, $conf or die "Can't open $conf";
while (<IN>) {
if (m/^\s*needs_sphinx\s*=\s*[\'\"]([\d\.]+)[\'\"]/) {
@@ -293,18 +291,7 @@ sub check_sphinx()
die "Can't get needs_sphinx version from $conf" if (!$min_version);
- open IN, $requirement_file or die "Can't open $requirement_file";
- while (<IN>) {
- if (m/^\s*Sphinx\s*==\s*([\d\.]+)$/) {
- $default_version=$1;
- last;
- }
- }
- close IN;
-
- die "Can't get default sphinx version from $requirement_file" if (!$default_version);
-
- $virtenv_dir = $virtenv_prefix . $default_version;
+ $virtenv_dir = $virtenv_prefix . "latest";
my $sphinx = get_sphinx_fname();
if ($sphinx eq "") {
@@ -318,8 +305,8 @@ sub check_sphinx()
die "$sphinx didn't return its version" if (!$cur_version);
if ($cur_version lt $min_version) {
- printf "ERROR: Sphinx version is %s. It should be >= %s (recommended >= %s)\n",
- $cur_version, $min_version, $default_version;
+ printf "ERROR: Sphinx version is %s. It should be >= %s\n",
+ $cur_version, $min_version;
$need_sphinx = 1;
return;
}
--
2.43.2
On Tue, Feb 27, 2024 at 2:14 PM Lukas Bulwahn <[email protected]> wrote:
>
> As discussed (see Links), there is some inertia to move to the recent
> Sphinx versions for the doc build environment.
>
> As first step, drop the version constraints and the related comments.
> Then, the sphinx-pre-install script will fail though with:
>
> Can't get default sphinx version from ./Documentation/sphinx/requirements.txt at ./scripts/sphinx-pre-install line 305.
>
> The script simply expects to parse a version constraint with Sphinx in the
> requirements.txt. That version is used in the script for suggesting the
> virtualenv directory name.
>
> To suggest a virtualenv directory name, when there is no version given in
> the requirements.txt, one could try to guess the version that would be
> downloaded with 'pip install -r Documentation/sphinx/requirements.txt'.
> However, there seems no simple way to get that version without actually
> setting up the venv and running pip. So, instead, name the directory with
> the fixed name 'sphinx_latest'.
>
> Finally update the Sphinx build documentation to reflect this directory
> name change.
>
> Link: https://lore.kernel.org/linux-doc/[email protected]/
> Link: https://lore.kernel.org/linux-doc/[email protected]/
>
> Signed-off-by: Lukas Bulwahn <[email protected]>
Oops, I was a bit quick on sending this out, I wanted to add those
remarks for the patch discussion:
This change seems to work for my setup, but I have really only dipped my
toes into the waters of this sphinx-pre-install script.
I only dropped the version constraints, but possibly one can even drop
some of the packages in the requirements.txt, as they are pulled in
automatically by Sphinx dependencies.
So, I am happy to get your feedback, but I am well aware about its
potential to be improved and the lack of my deep knowledge about the
script. I hope, though, you can test it in your setup and confirm if
it works as expected and then we can discuss the details (e.g.,
naming).
Lukas
Lukas Bulwahn <[email protected]> writes:
> This change seems to work for my setup, but I have really only dipped my
> toes into the waters of this sphinx-pre-install script.
>
> I only dropped the version constraints, but possibly one can even drop
> some of the packages in the requirements.txt, as they are pulled in
> automatically by Sphinx dependencies.
That's a cleanup we can do at any time, I guess. I note that not all of
them get pulled in correctly, though; after installing 7.2.6 with pip, I
still had to get pyyaml separately before it would work.
> So, I am happy to get your feedback, but I am well aware about its
> potential to be improved and the lack of my deep knowledge about the
> script. I hope, though, you can test it in your setup and confirm if
> it works as expected and then we can discuss the details (e.g.,
> naming).
I think this is the direction we need to go. We can add a separate
requirements file for successful installation of 2.4.x later if that's
really needed. Unless I hear screams, my plan is to apply this.
Thanks,
jon
On 27/02/2024 14:14, Lukas Bulwahn wrote:
> As discussed (see Links), there is some inertia to move to the recent
> Sphinx versions for the doc build environment.
[...]
> diff --git a/Documentation/sphinx/requirements.txt b/Documentation/sphinx/requirements.txt
> index 5d47ed443949..1f3b98eee2c9 100644
> --- a/Documentation/sphinx/requirements.txt
> +++ b/Documentation/sphinx/requirements.txt
> @@ -1,6 +1,4 @@
> -# jinja2>=3.1 is not compatible with Sphinx<4.0
> -jinja2<3.1
> -# alabaster>=0.7.14 is not compatible with Sphinx<=3.3
> -alabaster<0.7.14
> -Sphinx==2.4.4
> +jinja2
> +alabaster
> +Sphinx
> pyyaml
I know you wrote this as well, but just for the record I tried dropping
jinja2 from this list and it still pulled it in automatically:
Collecting Jinja2>=3.0
Using cached Jinja2-3.1.3-py3-none-any.whl (133 kB)
> diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install
> index de0de5dd676e..4c781617ffe6 100755
> --- a/scripts/sphinx-pre-install
> +++ b/scripts/sphinx-pre-install
> @@ -280,8 +280,6 @@ sub get_sphinx_version($)
>
> sub check_sphinx()
> {
> - my $default_version;
> -
> open IN, $conf or die "Can't open $conf";
> while (<IN>) {
> if (m/^\s*needs_sphinx\s*=\s*[\'\"]([\d\.]+)[\'\"]/) {
> @@ -293,18 +291,7 @@ sub check_sphinx()
>
> die "Can't get needs_sphinx version from $conf" if (!$min_version);
>
> - open IN, $requirement_file or die "Can't open $requirement_file";
> - while (<IN>) {
> - if (m/^\s*Sphinx\s*==\s*([\d\.]+)$/) {
> - $default_version=$1;
> - last;
> - }
> - }
> - close IN;
> -
> - die "Can't get default sphinx version from $requirement_file" if (!$default_version);
> -
> - $virtenv_dir = $virtenv_prefix . $default_version;
> + $virtenv_dir = $virtenv_prefix . "latest";
>
> my $sphinx = get_sphinx_fname();
> if ($sphinx eq "") {
> @@ -318,8 +305,8 @@ sub check_sphinx()
> die "$sphinx didn't return its version" if (!$cur_version);
>
> if ($cur_version lt $min_version) {
> - printf "ERROR: Sphinx version is %s. It should be >= %s (recommended >= %s)\n",
> - $cur_version, $min_version, $default_version;
> + printf "ERROR: Sphinx version is %s. It should be >= %s\n",
> + $cur_version, $min_version;
> $need_sphinx = 1;
> return;
> }
Tried with a few different versions:
$ (. sphinx-2.4.4/bin/activate && scripts/sphinx-pre-install)
Detected OS: Ubuntu 22.04.3 LTS.
Sphinx version: 2.4.4
You may also use the newer Sphinx version 7.2.6 with:
. /home/vegard/linux/sphinx_latest/bin/activate
[...]
$ (. sphinx-2.0/bin/activate && scripts/sphinx-pre-install)
ERROR: Sphinx version is 2.0.0. It should be >= 2.4.4
Detected OS: Ubuntu 22.04.3 LTS.
Sphinx version: 2.0.0
Need to activate Sphinx (version 7.2.6) on virtualenv with:
. /home/vegard/linux/sphinx_latest/bin/activate
[...]
$ scripts/sphinx-pre-install
Detected OS: Ubuntu 22.04.3 LTS.
Sphinx version: 4.3.2
All optional dependencies are met.
Needed package dependencies are met.
One remark I have is that it didn't encourage me to upgrade to 7.2.6 in
the last one (using the system Sphinx 4.3.2) although it did for the
2.4.4 virtualenv. Maybe that's expected. I didn't look into it. Anyway,
FWIW:
Tested-by: Vegard Nossum <[email protected]>
Vegard
On Thu, 29 Feb 2024 15:39:31 +0100, Vegard Nossum wrote:
> [...]
>
> $ scripts/sphinx-pre-install
> Detected OS: Ubuntu 22.04.3 LTS.
> Sphinx version: 4.3.2
>
>
> All optional dependencies are met.
> Needed package dependencies are met.
>
>
> One remark I have is that it didn't encourage me to upgrade to 7.2.6 in
> the last one (using the system Sphinx 4.3.2) although it did for the
> 2.4.4 virtualenv. Maybe that's expected. I didn't look into it. Anyway,
Yes, it's expected.
Sphinx 3.4.3 provided as distro packages of Debian 11 (bullseye),
RHEL 9, and so on is good enough for kernel documentation.
Suggesting upgrade to a latest release would be noisy.
The version is assigned to $rec_version in sphinx-pre-install.
As a fix to requirements.txt for v6.8, this looks to me like a nice
minimal change.
Lukas, many thanks for doing this.
Reviewed-by: Akira Yokosawa <[email protected]>
Thanks, Akira
On Fri, Mar 1, 2024 at 3:33 AM Akira Yokosawa <[email protected]> wrote:
>
> (snipped)
>
> Lukas, many thanks for doing this.
>
> Reviewed-by: Akira Yokosawa <[email protected]>
>
Akira-san, thanks for the review!
Lukas
On Thu, Feb 29, 2024 at 3:39 PM Vegard Nossum <vegard.nossum@oraclecom> wrote:
>
>
> On 27/02/2024 14:14, Lukas Bulwahn wrote:
> > As discussed (see Links), there is some inertia to move to the recent
> > Sphinx versions for the doc build environment.
>
> [...]
>
> > diff --git a/Documentation/sphinx/requirements.txt b/Documentation/sphinx/requirements.txt
> > index 5d47ed443949..1f3b98eee2c9 100644
> > --- a/Documentation/sphinx/requirements.txt
> > +++ b/Documentation/sphinx/requirements.txt
> > @@ -1,6 +1,4 @@
> > -# jinja2>=3.1 is not compatible with Sphinx<4.0
> > -jinja2<3.1
> > -# alabaster>=0.7.14 is not compatible with Sphinx<=3.3
> > -alabaster<0.7.14
> > -Sphinx==2.4.4
> > +jinja2
> > +alabaster
> > +Sphinx
> > pyyaml
>
> I know you wrote this as well, but just for the record I tried dropping
> jinja2 from this list and it still pulled it in automatically:
Vegard, I took your suggestion and removed jinja2 from the
requirements.txt in my patch v2:
https://lore.kernel.org/linux-doc/[email protected]/
So, there is no need for any further future one-line deletion patch.
Jonathan, please pick the patch v2.
Lukas