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
