GCC documentation: porting to Sphinx

[Martin Liška]

On 6/1/21 3:31 PM, Michael Matz wrote:
> Hello,
> 
> On Tue, 1 Jun 2021, Martin Liška wrote:
> 
>> On 5/31/21 5:49 PM, Michael Matz wrote:
>>> Hello Martin,
>>>
>>> On Mon, 31 May 2021, Martin Liška wrote:
>>>
>>>> I've made quite some progress with the porting of the documentation and
>>>> I would like to present it to the community now:
>>>> https://splichal.eu/scripts/sphinx/
>>>>    Note the documentation is automatically ([1]) generated from texinfo with
>>>> a
>>>> GitHub workflow ([2]).
>>>
>>> One other thing I was recently thinking about, in the Spinx vs. texinfo
>>> discussion: locally available documentation browsable/searchable in
>>> terminal with info(1) (or equivalents).
>>
>> Yes, that's handy.
>>
>>> I think the above (i.e. generating .rst from the texinfo file) would
>>> immediately nullify all my worries.  So, just to be extra sure: your
>>> proposal now is to generate the .rst files, and that .texinfo remains
>>> the maintained sources, right?
>>
>> No, .texinfo files will be gone. However, Sphinx can output to info
>> format:
>> https://www.sphinx-doc.org/en/master/man/sphinx-build.html#cmdoption-sphinx-build-M
> 
> I see, that's good to hear.
> 
>> And I've just added the generated Info pages here:
>> https://splichal.eu/scripts/sphinx/
> 
> Okay, but there's something amiss, just compare a local gcc.info with
> that.  The sphinx generated one seems to only contain command line
> options, but none of the other topics, in particular it seems to contain
> the "Invoking GCC" chapter (and only that) as top-level, and all other
> ones are missing (like "C implementation", "C++ implementation", "C
> extension", and so on).

You are right, I reduced that to 'Invoking GCC', which is simply what 'man gcc'
presents. However, I moved that back to the entire GCC manual what you can
see now in the info page.

> 
> Looking at gccint.info I also seem quite some confusion, it's unclear to
> me if content is missing or not.  But e.g. the top-level structure has a
> different order (a less logical one, this one is btw. shared with the
> order of the HTML generated docu, so it's probably specific to sphinx
> setup or such).

Yes, the organization was bad and I fixed that. Now it's much better.

Martin

> 
> Ignoring that missing content what is there right now does seem somewhat
> acceptable for local use, though.
> 
> 
> Ciao,
> Michael.
>