GCC documentation: porting to Sphinx

[Martin Liška]

On 6/28/21 12:23 PM, Arnaud Charlet wrote:
>> I've got something that is very close to be a patch candidate that can be
>> eventually merged. Right now, the patches are available here:
>> https://gcc.gnu.org/git/gitweb.cgi?p=gcc.git;a=log;h=refs/users/marxin/heads/sphinx-v3
> 
> FWIW I would prefer to review the changes posted here directly with all
> the details.

Sure, I'm going to send a proper patch set in an hour or so. As mentioned, I won't be able to attach
some of the patches as they will exceed 1MB email limit.

> 
> In particular can you explain the motivation behind all the changes in the
> gcc/ada/doc directory?

Sure:
1) All Sphinx manuals live in a directory where index page is called index.rst. That's why
I moved e.g. this: gcc/ada/doc/{gnat_rm.rst => gnat_rm/index.rst}
2) I moved latex_elements.py to ada_latex_elements.py as it clashes with Sphinx global variable
you modify in Sphinx config files
3) I created a shared Ada config (adabaseconf.py) that extends doc/baseconf.py and sets what
is shared in between 3 Ada manuals.
4) gnu_free_documentation_license.rst is taken from $root/doc/

> That's lots of moving files around, so I'd like
> to understand why and make sure these are not gratuituous changes, since
> move files around is always tricky and I'd rather not have to undo it
> later in case this causes troubles or have unexpected consequences.

Hope I explained all the reasonable changes?

> 
> Otherwise, glad to see the switch to sphinx finally moving in gcc!

You're welcome. I would be interested in testing your PRO configuration (based on Gnat_Build_Type,
see get_gnat_build_type) and I'm curious if you're fine with Sphinx template change?
It will be the same as for other manuals.

Cheers,
Martin

> 
> Arno
>