RFC: Experimental use of Sphinx for GCC documentation

[David Malcolm]

On Mon, 2015-11-09 at 16:37 -0700, Sandra Loosemore wrote:
> On 11/08/2015 06:55 AM, David Malcolm wrote:
> > I've been experimenting with using Sphinx [1] for GCC's documentation.
> >
> > [snip]
> >
> > The primary advantages of .rst/sphinx over .texi/texinfo I see are in
> > the generated HTML:
> >
> > * sane, stable URLs (so e.g. there is a reliable URL for the docs for,
> > say, "-Wall").
> >
> > * a page-splitting structure that make sense, to me, at least [3]
> >
> > * much more use of markup, with restrained and well-chosen CSS
> > (texinfo's HTML seems to ignore much of the inline markup in
> > the .texinfo file)
> >
> > * autogenerated internal links, so that almost everything is clickable,
> > and will take you somewhere sane, by default
> >
> > * syntax-highlighting of code examples, with support for multiple
> > programming languages (note the mixture of C, C++, Fortran, etc in the
> > docs for the gcc options).
> >
> > * looks modern and fresh (IMHO), letting casual observers see that the
> > project is alive and kicking.
> >
> >
> > Thoughts?
> 
> If we're going to switch documentation formats, I'd rather we used 
> DocBook.  I've had to use "restructured text" before and found it really 
> awkward.

My own preference is the opposite; I've used DocBook and rst, and I find
DocBook to be the awkward one [1].  I think DocBook may be OK as an
interchange format, but I find it overly verbose to author and to read
in plain-text form.

(I'm not so fond of some parts of .rst's inline markup syntax, but I
find its structural aspects to be extremely expressive and concise;
overall I find it a joy to work with).

> But, personal preferences aside, I also think it's more important that 
> we commit documentation-person resources to making the content more 
> correct, readable, and better organized, than to making the HTML output 
> look "modern and fresh", or worse yet, translating the docs to another 
> format and having to proofread them for conversion goofs.

Correct, readable and well-organized documentation are laudable goals...
but I think that, to a first approximation, we're already there: I just
feel that the content is hidden behind a poor tool chain.

I believe that no matter how good we make the .texi files, the issues
with URLs, HTML page-splitting, etc with how texinfo's HTML generation
works will hold gcc back.

> BTW, Mentor Graphics' toolchains ship with a custom HTML stylesheet for 
> the generated manuals, to make them a little "prettier".  Maybe 
> something like that would go a long way towards solving the perceived 
> problems here? 

I'm interested in seeing that, though presumably the URL and
page-splitting issues would remain (is this at the CSS level, or do you
make deeper changes to the HTML generation?)


> Or improvements to texinfo's HTML generation.

texinfo is implemented in Perl, and FWIW, for me to help, that's a
showstopper (sprry; I've tried several times to get my head around Perl,
but my brain seems incompatible with it).


One other approach might be to retain .texi as the canonical format, but
have a optional custom HTML generator (perhaps using texi2rst to
generate .rst for sphinx, this time as an intermediate step during "make
html", rather than as a one-time conversion).  The main thing I think
it's missing is a way to express the language of embedded source
examples, so that they can be syntax-highlighted.


Thanks; I hope this is constructive.
Dave

[1] fwiw, my opinion on this has changed; a decade or so ago I worked on
a DocBook editor,  http://conglomerate.org/