RFC: Sphinx for GCC documentation

[Martin Liška]

On 6/4/21 4:24 PM, Koning, Paul wrote:
> 
> 
>> On Jun 4, 2021, at 3:55 AM, Tobias Burnus <tobias@codesourcery.com> 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/
>>
>> The HTML output looks quite nice.
>>
>> 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
> 
> Explicit line breaks are likely to be wrong depending on the reader's window size.  I would suggest setting the table to have cells with line-wrapped contents.  That would typically be the default in HTML, I'm curious why that is not happening here.

Note that Sphinx supports 2 types of tables: Grid Table and Simple table. We prefer the later and
one can do proper line breaking in the Grid type.

https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#tables

Anyway, this is resolved as I use more appropriate directive:
https://splichal.eu/scripts/sphinx/gfortran/_build/html/intrinsic-procedures/access-checks-file-access-modes.html

Martin

> 
> 	paul
> 
>