GCC documentation: porting to Sphinx
Michael Matz
matz@suse.de
Tue Jun 1 13:31:15 GMT 2021
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.
More information about the Gcc-patches
mailing list