Re: GCC documentation: porting to Sphinx

["Martin Liška" <mliska@suse.cz>]

Hello.

I've just pushed the rebased branch here:
https://gcc.gnu.org/git/gitweb.cgi?p=gcc.git;a=log;h=refs/users/marxin/heads/sphinx-v4

which I force push once I rebase it. One can fetch the branch with:
$ git fetch origin refs/users/marxin/heads/sphinx-v4

Generated output (directly made from GCC source tree) can be seen here:
https://splichal.eu/gccsphinx-final/

Changes since the previous version:

1) rebased on the current master (including addition of new target hooks, etc.)
2) two new directive/roles were added in order to not abuse 'option' directive:
    gcc-attr (function/label/... attribute) and gcc-param (--param foo=bar).
    Addition was quite straightforward and we would benefit as these attributes
    and parameters will be listed grouped in the Index:
    https://splichal.eu/gccsphinx-final/html/gcc/genindex.html
3) default syntax language was set to 'none'; made issue for e.g. chunks in license pages
    where a random Python keywords were highlighted

What needs to be done (TODO list):

1) Cross manual references are missing - we have some of them and Sphinx has nice support for it:
    https://docs.readthedocs.io/en/stable/guides/intersphinx.html
2) Remove `Texinfo Manuals` section in GCC internal manual
3) Document required packages for PDF, MAN, HTML, ..
4) Write How to write documentation, we can take inspiration from Kernel:
    https://www.kernel.org/doc/html/latest/doc-guide/index.html
5) Update update_web_docs_git - that will simply run Sphinx' Makefile
6) URL emission code needs to be changed in diagnostics.c
7) link emission should be ignored in Info builder
8) epub target should be added to Makefiles
9) function/struct/type attribute definition should be simplified as
    :gcc-attr: attr_name ("options")
    does not work with a reference to it: :gcc-atr:`attr_name`
    An attribute format should be placed into the attr description.
10) default domain should be switched to cpp, will lead to warnings as seen here:
     https://github.com/sphinx-doc/sphinx/issues/9535
11) many function and macros in gccint should promoted to '.. function::' and
     '.. macro::' directive
12) various smaller formatting issues need to be addressed

Known limitations:
1) chapter description (in TOC listing) is dropped in info pages
2) PDF output puts item description on the same line as item definition - noticed by Tamar

As previously mentioned, I'm willing to work on the majority of the points mentioned in the TODO list.
Now I see the current patchset in a reasonable shape and I'm asking the community for approval of the changes?
And I would appreciate a help with any of the items listed in the TODO list.

Thanks,
Martin