RFC: Sphinx for GCC documentation

[Martin Liška]

On 6/4/21 9:55 AM, Tobias Burnus wrote:
> Hello,
> 
> On 13.05.21 13:45, Martin Liška wrote:
>> On 4/1/21 3:30 PM, Martin Liška wrote:
>>> That said, I'm asking the GCC community for a green light before I
>>> invest
>>> more time on it?
>> So far, I've received just a small feedback about the transition. In
>> most cases positive.
>>
>> [1] https://splichal.eu/scripts/sphinx/
> 

Hi.

> The HTML output looks quite nice.

Thanks.

> 
> What I observed:
> 
> * Looking at
>    https://splichal.eu/scripts/sphinx/gfortran/_build/html/intrinsic-procedures/access-checks-file-access-modes.html
> why is the first argument description in bold?
> It is also not very readable to have a scollbar there – linebreaks would be better.
> → I think that's because the assumption is that the first line contains a header
>    and the rest the data

I've converted the problematic table to '.. function::' directive that has :returns: and :param: arguments.
Hope the output is fine now?

> 
> * https://splichal.eu/scripts/sphinx/gfortran/_build/latex/gfortran.pdf
>    If I look at page 92 (alias 96), 8.2.13 _gfortran_caf_sendget, the first column
>    is too small to fit the argument names. – Admittedly, the current gfortran.pdf
>    is not much better – it is very tight but just fits. I don't know how to fix this.

This is also converted and should look much better.

> 
> * I note that we write before the argument index, that those are without -/-- prefix
>    but that's not true. Something to fix after the conversation.

Can you please show me a few examples of it?

> 
> * The syntax highlighting for gfortran is odd. Looking at @smallexample:
> - intrinsic.texi: All Fortran examples (F90/free-form)
> - gfc-internals.texi: 4x Fortran, 4x C, 3x plain text
> - gfortran.texi: Shell, Fortran, C, plain text.
> - invoke.texi: 4x Shell, 2x C, 4x Fortran

Should be fixed now as I set 'fortran' code-block in the fortran manual.
Right now, there are few warnings that a code block is C/C++, but that's
quite a small fallout.

> Does not seem to be that simple, but it would be nice if at least all in
> intrinsic.texi would be marked as Fortran.

Should be better now?

> 
> Actually, I do not quite understand when the output is formatted a C (wrongly
> or rightly) as Fortran (rarely but correctly) as plain or in some odd formatting
> which randomly highlights some examples.

We make quests based on keyworks in a code-block and we also consider texinfo filename.

> Possibly also an item for after the conversion.

Sure, there are still some warnings that can be seen with 'make html' (or other target).

Thanks for review,
Martin

> 
> Tobias
> 
> -----------------
> Mentor Graphics (Deutschland) GmbH, Arnulfstrasse 201, 80634 München Registergericht München HRB 106955, Geschäftsführer: Thomas Heurung, Frank Thürauf