[PATCH] contrib: use sphinx-build from a venv

[PATCH] contrib: use sphinx-build from a venv

[Martin Liška]

Hi.

As you likely know, I'm still working on transition of the current docs to Sphinx.
But for now, I've sent a modernizing patches for the current libgccjit documentation
and I will need a more recent version of Sphinx.

Can please a maintainer install the package from pip?

Something like:
virtualenv /home/gcc/venv && /home/gcc/venv/bin/pip install Sphinx

or a similar location?

Thanks,
Martin

maintainer-scripts/ChangeLog:

	* update_web_docs_git: Use sphinx-build from a venv so that
	we can use a recent version.
---
 maintainer-scripts/update_web_docs_git | 21 ++++++---------------
 1 file changed, 6 insertions(+), 15 deletions(-)

diff --git a/maintainer-scripts/update_web_docs_git b/maintainer-scripts/update_web_docs_git
index 996d29bfb68..4b01b3dc1c0 100755
--- a/maintainer-scripts/update_web_docs_git
+++ b/maintainer-scripts/update_web_docs_git
@@ -176,23 +176,14 @@ for file in $MANUALS; do
   fi
 done
 
-# The jit is a special-case, using sphinx rather than texinfo.
-# Specifically, the jit docs need sphinx 1.0 or later.
+# The jit is a special-case, using Sphinx rather than texinfo.
+# Specifically, the jit docs need Sphinx 3.0 or later.
 #
-# The jit/docs Makefile uses the executable $(SPHINXBUILD),
-# defaulting to "sphinx-build".
-#
-# sphinx is packaged in Fedora and EPEL 6 within "python-sphinx",
-# in RHEL 8 within "python3-sphinx",
-# and in openSUSE within "python-Sphinx".
-#
-# For EPEL6, python-sphinx is sphinx 0.6.6, which is missing various
-# directives (e.g. ":c:macro:"), so we need the variant
-# python-sphinx10 package.  The latter installs its executable as
-#   /usr/bin/sphinx-1.0-build
-# so we needed to override SPHINXBUILD with this when invoking "make".
+# Use the Sphinx installed in a virtual environment so that
+# we don't depend on a system package.
+
 pushd gcc/gcc/jit/docs
-make html || true
+make html SPHINXBUILD=/home/gcc/venv/bin/sphinx-build || true
 popd
 cp -a gcc/gcc/jit/docs/_build/html jit
 mkdir -p $DOCSDIR/jit
-- 
2.37.1

Re: [PATCH] contrib: use sphinx-build from a venv

[Martin Liška]

CCing overseers and Frank.

Can you please help me with that?

Thanks,
Martin

On 7/25/22 16:00, Martin Liška wrote:
> Hi.
> 
> As you likely know, I'm still working on transition of the current docs to Sphinx.
> But for now, I've sent a modernizing patches for the current libgccjit documentation
> and I will need a more recent version of Sphinx.
> 
> Can please a maintainer install the package from pip?
> 
> Something like:
> virtualenv /home/gcc/venv && /home/gcc/venv/bin/pip install Sphinx
> 
> or a similar location?
> 
> Thanks,
> Martin
> 
> maintainer-scripts/ChangeLog:
> 
> 	* update_web_docs_git: Use sphinx-build from a venv so that
> 	we can use a recent version.
> ---
>  maintainer-scripts/update_web_docs_git | 21 ++++++---------------
>  1 file changed, 6 insertions(+), 15 deletions(-)
> 
> diff --git a/maintainer-scripts/update_web_docs_git b/maintainer-scripts/update_web_docs_git
> index 996d29bfb68..4b01b3dc1c0 100755
> --- a/maintainer-scripts/update_web_docs_git
> +++ b/maintainer-scripts/update_web_docs_git
> @@ -176,23 +176,14 @@ for file in $MANUALS; do
>    fi
>  done
>  
> -# The jit is a special-case, using sphinx rather than texinfo.
> -# Specifically, the jit docs need sphinx 1.0 or later.
> +# The jit is a special-case, using Sphinx rather than texinfo.
> +# Specifically, the jit docs need Sphinx 3.0 or later.
>  #
> -# The jit/docs Makefile uses the executable $(SPHINXBUILD),
> -# defaulting to "sphinx-build".
> -#
> -# sphinx is packaged in Fedora and EPEL 6 within "python-sphinx",
> -# in RHEL 8 within "python3-sphinx",
> -# and in openSUSE within "python-Sphinx".
> -#
> -# For EPEL6, python-sphinx is sphinx 0.6.6, which is missing various
> -# directives (e.g. ":c:macro:"), so we need the variant
> -# python-sphinx10 package.  The latter installs its executable as
> -#   /usr/bin/sphinx-1.0-build
> -# so we needed to override SPHINXBUILD with this when invoking "make".
> +# Use the Sphinx installed in a virtual environment so that
> +# we don't depend on a system package.
> +
>  pushd gcc/gcc/jit/docs
> -make html || true
> +make html SPHINXBUILD=/home/gcc/venv/bin/sphinx-build || true
>  popd
>  cp -a gcc/gcc/jit/docs/_build/html jit
>  mkdir -p $DOCSDIR/jit

Re: [PATCH] contrib: use sphinx-build from a venv

[Frank Ch. Eigler]

Hi -

> CCing overseers and Frank.
> Can you please help me with that?

> > Can please a maintainer install the package from pip?
> > Something like:
> > virtualenv /home/gcc/venv && /home/gcc/venv/bin/pip install Sphinx
> > or a similar location?

The gccadmin team can do this kind of thing without overseer/root
privileges, or indeed so can any local shell-privileged user.

(That said, rhel8 includes sphynx 1.7.6 - are you sure that's
not satisfactory?)

- FChE

Re: [PATCH] contrib: use sphinx-build from a venv

[Jonathan Wakely]

On Tue, 26 Jul 2022 at 12:45, Frank Ch. Eigler <fche@redhat.com> wrote:
>
> Hi -
>
> > CCing overseers and Frank.
> > Can you please help me with that?
>
> > > Can please a maintainer install the package from pip?
> > > Something like:
> > > virtualenv /home/gcc/venv && /home/gcc/venv/bin/pip install Sphinx
> > > or a similar location?
>
> The gccadmin team can do this kind of thing without overseer/root
> privileges, or indeed so can any local shell-privileged user.

Yeah, I said I didn't want to install it that way without overseer
approval, as pip won't keep the packages up to date the way dnf
installations do.

> (That said, rhel8 includes sphynx 1.7.6 - are you sure that's
> not satisfactory?)

That's a different package (full text search engine), what's needed
here is python3-sphinx.

Re: [PATCH] contrib: use sphinx-build from a venv

[Frank Ch. Eigler]

Hi -

> > The gccadmin team can do this kind of thing without overseer/root
> > privileges, or indeed so can any local shell-privileged user.
> 
> Yeah, I said I didn't want to install it that way without overseer
> approval, as pip won't keep the packages up to date the way dnf
> installations do.

Indeed, but that's your own preference/responsibility and does not
affect the system, so no overseer oversight is necessary.

> > (That said, rhel8 includes sphynx 1.7.6 - are you sure that's
> > not satisfactory?)
> 
> That's a different package (full text search engine), what's needed
> here is python3-sphinx.

# rpm -q python3-sphinx
python3-sphinx-1.7.6-2.el8.noarch


- FChE

Re: [PATCH] contrib: use sphinx-build from a venv

[Jonathan Wakely]

On Tue, 26 Jul 2022 at 12:56, Frank Ch. Eigler wrote:
>
> Hi -
>
> > > The gccadmin team can do this kind of thing without overseer/root
> > > privileges, or indeed so can any local shell-privileged user.
> >
> > Yeah, I said I didn't want to install it that way without overseer
> > approval, as pip won't keep the packages up to date the way dnf
> > installations do.
>
> Indeed, but that's your own preference/responsibility and does not
> affect the system, so no overseer oversight is necessary.

OK, I can install it for Martin then.

> > > (That said, rhel8 includes sphynx 1.7.6 - are you sure that's
> > > not satisfactory?)
> >
> > That's a different package (full text search engine), what's needed
> > here is python3-sphinx.
>
> # rpm -q python3-sphinx
> python3-sphinx-1.7.6-2.el8.noarch

Oh right, yes, sorry, I got confused after I looked into the packages
myself. The "other sphinx" is in EPEL 8 as sphinx-2.2.11-15.el8

Re: [PATCH] contrib: use sphinx-build from a venv

[Martin Liška]

On 7/26/22 14:01, Jonathan Wakely via Gcc-patches wrote:
> On Tue, 26 Jul 2022 at 12:56, Frank Ch. Eigler wrote:
>>
>> Hi -
>>
>>>> The gccadmin team can do this kind of thing without overseer/root
>>>> privileges, or indeed so can any local shell-privileged user.
>>>
>>> Yeah, I said I didn't want to install it that way without overseer
>>> approval, as pip won't keep the packages up to date the way dnf
>>> installations do.
>>
>> Indeed, but that's your own preference/responsibility and does not
>> affect the system, so no overseer oversight is necessary.
> 
> OK, I can install it for Martin then.

Thanks Jonathan.

> 
>>>> (That said, rhel8 includes sphynx 1.7.6 - are you sure that's
>>>> not satisfactory?)
>>>
>>> That's a different package (full text search engine), what's needed
>>> here is python3-sphinx.
>>
>> # rpm -q python3-sphinx
>> python3-sphinx-1.7.6-2.el8.noarch
> 
> Oh right, yes, sorry, I got confused after I looked into the packages
> myself. The "other sphinx" is in EPEL 8 as sphinx-2.2.11-15.el8

Sorry, but it's too old, we actually need a release that was released this week ;)
(5.1.0).

Thanks,
Martin