GCC documentation: porting to Sphinx

Martin Liška mliska@suse.cz
Fri Jun 4 07:27:05 GMT 2021

On 6/3/21 7:16 PM, Joseph Myers wrote:
> 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).

Sure, that makes sense.

> 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).

Yeah, I used the f-string syntax only at one place and it does not pay off.

> Formally 3.5 and older are no longer supported
> upstream, but certainly still present in some maintained long-term-support
> distribution versions.

Makes sense.

>> 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").

I checked that and the template needs at least version 1.6:

so I added needs_sphinx to baseconf.py:

The following message is displayed when one builds a manual:

$ make html

sphinx-build -b "html" -d _build/doctrees    . "_build/html"

Running Sphinx v4.0.2

Sphinx version error:

This project needs at least Sphinx v66.6 and therefore cannot be built with this version.

make: *** [Makefile:96: html] Error 2


More information about the Gcc-patches mailing list