Akira Yokosawa <akiyks@xxxxxxxxx> writes: > With this patch applied, I get a confusing looking warning from > "make htmldocs" on a machine where the Sphinx version is 2.4.5: > > -------- > Warning: It is recommended at least Sphinx version 3.4.3. > To upgrade Sphinx, use: > > /home/akira/sphinx-2.4.5/bin/python3 -m venv sphinx_2.4.4 > . sphinx_2.4.4/bin/activate > pip install -r ./Documentation/sphinx/requirements.txt > > If you want to exit the virtualenv, you can use: > deactivate > -------- > > Looks like we need to update requirements.txt as well so that it > installs Sphinx 3.4.3. Appended below is a fixup patch to that > effect. So I can apply this, certainly, but it makes me feel like perhaps we need to reconsider our approach a bit. It's kind of weird that we have a minimum supported version, then a semi-random "recommended" version that is still pretty old. Is there a reason to suggest to people that they should run something other than current sphinx, especially if they are updating it anyway? So our "recommended version" is really "recommended *minimum* version"? > ----8<---- > From: Akira Yokosawa <akiyks@xxxxxxxxx> > Subject: [PATCH] docs: sphinx/requirement.txt: Reflect recommended Sphinx version > > sphinx_pre_install parses the version of Sphinx in requirements.txt > and emits messages based on it. > Update requirements.txt so that it installs Sphinx 3.4.3, as well as > the examples in documentation. > > Signed-off-by: Akira Yokosawa <akiyks@xxxxxxxxx> > --- > Documentation/doc-guide/sphinx.rst | 14 +++++++------- > Documentation/sphinx/requirements.txt | 4 +++- > 2 files changed, 10 insertions(+), 8 deletions(-) > > diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst > index 3d125fb4139d..5227a2611026 100644 > --- a/Documentation/doc-guide/sphinx.rst > +++ b/Documentation/doc-guide/sphinx.rst > @@ -48,13 +48,13 @@ 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 Sphinx version 3.4.3, 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_3.4.3 > + $ . sphinx_3.4.3/bin/activate > + (sphinx_3.4.3) $ pip install -r Documentation/sphinx/requirements.txt Here we could take version numbers out entirely; otherwise we'll always be updating this. > -After running ``. sphinx_2.4.4/bin/activate``, the prompt will change, > +After running ``. sphinx_3.4.3/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. > @@ -118,8 +118,8 @@ command line options for your distro:: > You should run: > > sudo dnf install -y texlive-luatex85 > - /usr/bin/virtualenv sphinx_2.4.4 > - . sphinx_2.4.4/bin/activate > + /usr/bin/virtualenv sphinx_3.4.3 > + . sphinx_3.4.3/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/sphinx/requirements.txt b/Documentation/sphinx/requirements.txt > index 335b53df35e2..89329e67e788 100644 > --- a/Documentation/sphinx/requirements.txt > +++ b/Documentation/sphinx/requirements.txt > @@ -1,3 +1,5 @@ > # jinja2>=3.1 is not compatible with Sphinx<4.0 > jinja2<3.1 > -Sphinx==2.4.4 > +# docutils>=0.18 is not compatible with 3.0 <= Sphinx < 4.0 > +docutils<0.18 > +Sphinx==3.4.3 I'd forgotten about the docutils fun. I wonder of our recommended minimum should actually be 4.0, then here we could put simply: Sphinx>4.0 ? Thanks, jon
