RFC: Sphinx for GCC documentation

[Martin Liška]

On 4/7/21 7:40 PM, Joseph Myers wrote:
> On Wed, 7 Apr 2021, Michael Matz wrote:
> 
>> Random snippet for what I mean: the .texi contains:
>>
>> "The @code{access} attribute specifies that a function to whose
>> by-reference arguments the attribute applies accesses the referenced
>> object according to @var{access-mode}.  The @var{access-mode} argument is
>> required and must be"
>>
>> the .rst has:
>>
>> "The ``access`` attribute specifies that a function to whose by-reference
>> arguments the attribute applies accesses the referenced object according
>> to :samp:`{access-mode}`.  The :samp:`{access-mode}` argument is required
>> and must be"
>>
>> So, @code{}/@var{} vs. `` `` / :samp:``.  Keeping in mind that
> 
> @var in Texinfo is orthogonal to whether something is literal code.  It
> looks like Sphinx's equivalent is {} inside :samp:`` (so not supporting
> the use case of @var outside literal code)?

Hello.

Yes, as Joseph says, it's equivalent to {var} within a :samp: directive as documented
here: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-samp

To be honest, if we really want, we can easily come up with even more roles.
But I don't think we would benefit from it.

...

> One other practical concern: it seems there's a one-to-one correspondence 

> of .rst files and (web)page.  Do we really want to maintain hundreds (or 

> how many?) .rst files, instead of 60 .texi files?

Well, based what I know about RST and Sphinx, it's pretty natural that one HTML page
corresponds to a single RST file.

Looking at famous users for Sphinx, I can see the following stats:

linux/Documentation> find . -name '*.rst' | wc -l

2807


godot-docs> find . -name '*.rst' | wc -l

1030


Martin