Re: RFC: Sphinx for GCC documentation

[Martin Sebor <msebor@gmail.com>]

On 4/1/21 7:30 AM, Martin Liška wrote:
> Hey.
> 
> I've returned to the David's project and I'm willing to finish his transition effort.
> I believe using Sphinx documentation can rapidly improve readability, both HTML and PDF version,
> of various GCC manuals ([1]). I've spent some time working on the David's texi2rsf conversion tool ([2])
> and I'm presenting a result that is not perfect, but can be acceptable after a reasonable
> amount of manual modifications.
> 
> So far I focused on the 2 biggest manuals we have:
> 
> (1) User documentation
> https://splichal.eu/sphinx/
> https://splichal.eu/sphinx/gcc.pdf
> 
> (2) GCC Internals Manual
> https://splichal.eu/sphinx-internal
> https://splichal.eu/sphinx-internal/gccint.pdf
> 
> I'm aware of missing pieces (thanks Joseph) and I'm willing to finish it.
> 
> That said, I'm asking the GCC community for a green light before I invest
> more time on it?

I like the output quite a bit, especially that things like option
references are automagically linked to their documentation.  I spent
just a bit of time looking through the HTML and PDF above and found
a few minor issues.  I suspect they're due to the conversion script
not being finished yet but just to confirm please see below.

Is the source we'd work with the same as what shows up when I click
the 'View page source' link?  (Or is there some preprocessing involved?)

I'm not excited about changing tools.  I like that Texinfo is a GNU
project; AFACT, Sphinx is not.  In the original thread David linked
to there was a suggestion to use Texinfo and Sphinx side by side.
I.e., keep .texi as the master source format and generate the .rst
files using the conversion script on demand.  Would making that
the first step of the transition be a viable option?  (With the idea
of giving it a try and deciding whether to convert after some time?)

Martin

[*] The linking doesn't always seem to work (e.g.,
:option:`-fabi-version=4` under -Wabi).  I'm guessing it's not yet
done in the conversion script (or there's no -fabi-version=4 in
the index) and not a Sphinx limitation.

It doesn't add links for attributes but presumably that could also
be made to happen in the conversion, right?

It doesn't seem to preserve newlines in long lists of options (like
under -Wall), so the result is just one long running series of options
that's hard (for me) to follow. Presumably there's a way to do that
too (add a newline after each :option?)

It mentions both the positive and the negative forms of options as
headings (like -Wmain, -Wno-main).  That seems superflous and, with
very long option names (I noticed this for example with
-Wno-analyzer-use-of-pointer-in-stale-stack-frame) the heading in
the PDF can run off the right edge of the page.  But based on
the source it also looks like it should be easy to adjust in
the conversion script if we wanted to keep just one form, right?


> 
> Cheers,
> Martin
> 
> [1] https://gcc.gnu.org/onlinedocs/
> [2] https://github.com/davidmalcolm/texi2rst
>