Received-SPF: pass (google.com: domain of linux-kernel+bounces-83310-linux.lists.archive=gmail.com@vger.kernel.org designates 2604:1380:45d1:ec00::1 as permitted sender) client-ip=2604:1380:45d1:ec00::1;
Precedence: bulk
MIME-Version: 1.0
References: <20240227131410.35269-1-lukas.bulwahn@gmail.com>
In-Reply-To: <20240227131410.35269-1-lukas.bulwahn@gmail.com>
From: Lukas Bulwahn <lukas.bulwahn@gmail.com>
Date: Tue, 27 Feb 2024 14:25:03 +0100
Message-ID: <CAKXUXMzejT7++UgpgE_eHbXTC+w0cz2-sPr3XawV6N2mCkupgw@mail.gmail.com>
Subject: Re: [PATCH] docs: drop the version constraints for sphinx and dependencies
To: Jonathan Corbet <corbet@lwn.net>, Mauro Carvalho Chehab <mchehab@kernel.org>, 
	Vegard Nossum <vegard.nossum@oracle.com>, Akira Yokosawa <akiyks@gmail.com>, 
	Jani Nikula <jani.nikula@linux.intel.com>, Randy Dunlap <rdunlap@infradead.org>, 
	linux-doc@vger.kernel.org
Cc: linux-kernel@vger.kernel.org
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

On Tue, Feb 27, 2024 at 2:14=E2=80=AFPM Lukas Bulwahn <lukas.bulwahn@gmail.=
com> 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/requiremen=
ts.txt at ./scripts/sphinx-pre-install line 305.
>
> The script simply expects to parse a version constraint with Sphinx in th=
e
> 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/874jf4m384.fsf@meer.lwn.net/
> Link: https://lore.kernel.org/linux-doc/20240226093854.47830-1-lukas.bulw=
ahn@gmail.com/
>
> Signed-off-by: Lukas Bulwahn <lukas.bulwahn@gmail.com>

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