GCC documentation: porting to Sphinx

[Joseph Myers]

On Thu, 3 Jun 2021, Martin Liška wrote:

> On 6/2/21 6:44 PM, Joseph Myers wrote:
> > On Wed, 2 Jun 2021, Joel Sherrill wrote:
> > 
> > > For RTEMS, we switched from texinfo to Sphinx and the dependency
> > > on Python3 for Sphinx has caused a bit of hassle. Is this going to be
> > > an issue for GCC?
> > 
> > What Sphinx (and, thus, Python) versions does the GCC manual build work
> > with?
> 
> I've just tried version 1.7.6 which we use for libgccjit and it's fine:
> https://gcc.gnu.org/onlinedocs/jit/
> 
> About Python version: I'm not planning supporting Python2, it's dead 10 years
> already.

There should be appropriate configure checks to avoid building manuals 
with too-old versions (i.e. disable the info/man manual build/install when 
Sphinx, or the Python version it's using, is too old or missing, not fail 
configure).

Actually this code is depending on Python 3.6 or later because of the use 
of an f-string in baseconf.py (without that f-string, it works with older 
versions, even 2.7).  Formally 3.5 and older are no longer supported 
upstream, but certainly still present in some maintained long-term-support 
distribution versions.

> I would recommend testing the build. You can simply clone:
> https://github.com/marxin/texi2rst-generated
> 
> and simply run 'make html' or 'make latexpdf'. Basic dependencies are
> mentioned here:
> https://github.com/marxin/texi2rst-generated#requirements

It appears "make html" works (with lots of WARNINGs) with Sphinx 1.6.1 but 
fails with 1.4 ("Theme error: unsupported theme option 
'prev_next_buttons_location' given").

-- 
Joseph S. Myers
joseph@codesourcery.com