Re: GCC documentation: porting to Sphinx

[Michael Matz <matz@suse.de>]

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

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

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


Ciao,
Michael.