Re: GCC documentation: porting to Sphinx

["Martin Liška" <mliska@suse.cz>]

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:
https://sphinx-rtd-theme.readthedocs.io/en/latest/installing.html#compatibility

so I added needs_sphinx to baseconf.py:
https://www.sphinx-doc.org/en/master/usage/configuration.html?highlight=conf.py#confval-needs_sphinx

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


Martin