GCC documentation: porting to Sphinx

Martin Liška mliska@suse.cz
Wed Jun 23 13:13:54 GMT 2021


Hello.

I've just made a first version of the patchset that sits in GCC source tree:
https://gcc.gnu.org/git/gitweb.cgi?p=gcc.git;a=log;h=refs/users/marxin/heads/sphinx-v2

Changes since the last submission:
1) I made a brief proofreading and fixed most of the formatting and other issues
2) target hook documentation was ported to RST format and gcc/genhooks generated a tm.rst.in
    that is then used via .. include:: directives
3) sphinx-build detection is implemented in gcc/configure.ac
3) make integration is done (currently covering info and man pages) for gcc and gcc/fortran targets

As before, one can see the result of generated output here:
https://splichal.eu/scripts/sphinx/

Known limitations:
1) I found a bug in man page generation that is currently fixed:
https://github.com/sphinx-doc/sphinx/issues/1860#issuecomment-861793094
Note the fix will appear in the upcoming 4.1.0 release. Without the patch, one can see wrong
font selection in a generated manual page

2) Right now, I rely on caching capability of sphinx-build. That means when no source change is detected,
sphinx-build exits immediately. However, it's not working for all targets (info, man) and I've suggested
a patch for it:
https://github.com/sphinx-doc/sphinx/issues/9359

3) I haven't prepared patch for .texi removal (should be quite easily doable).

4) the currently existing Sphinx manuals (Ada and libgccjit) are not integrated yet.

@Joseph: Can you share your thoughts about the used Makefile integration? What do you suggest for 2)
(note that explicit listing of all .rst file would be crazy)?

Thoughts?
Thanks,
Martin




More information about the Gcc mailing list