Re: GCC documentation: porting to Sphinx

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

On 8/10/21 17:43, Martin Liška wrote:
> 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

Hello.

There's updated version of the patch set sitting here:
refs/users/marxin/heads/sphinx-v5

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

And can be seen here.

> 
> 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

Changes since the previous version:
1) Cross manual references are working. It works surprisingly well and we have much more cross references now
(for things like options, ...).
2) I have a new version of update_web_docs_git that will be very simple:
    make -C doc html/pdf SOURCEDIR=... BUILDDIR=...
3) URL link creating was updated in diagnostics.c
4) I have a patch candidate that skips links in Info format:
    https://github.com/sphinx-doc/sphinx/pull/9578
5) default domain was switched to cpp and Sphinx community fixed various issues mentioned in:
    https://github.com/sphinx-doc/sphinx/issues/9535
6) I made one round of proof-reading of the manuals where I focused on the formatting issues

> 
> 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

What needs to be done (TODO list):

1) Remove `Texinfo Manuals` section in GCC internal manual
2) Document required packages for PDF, MAN, HTML, ..
3) Write How to write documentation, we can take inspiration from Kernel:
     https://www.kernel.org/doc/html/latest/doc-guide/index.html
4) epub target should be added to Makefiles
5) 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.
6) many function and macros in gccint should promoted to '.. function::' and
    '.. macro::' directive (partialy done)

Thoughts about current status of the migration process?

Thanks,
Martin

> 
> 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