RFC: Sphinx for GCC documentation
Martin Liška
mliska@suse.cz
Thu May 13 10:28:45 GMT 2021
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
More information about the Gcc-patches
mailing list