Porting the Docs to Sphinx - project status

[Martin Liška]

On 1/31/22 15:06, Martin Liška wrote:
> Hello.
> 
> It's about 5 months since the last project status update:
> https://gcc.gnu.org/pipermail/gcc-patches/2021-August/577108.html
> Now it's pretty clear that it won't be merged before GCC 12.1 gets released.
> 
> So where we are? I contacted documentation maintainers (Gerald, Sandra and Joseph) at the
> end of the year in a private email, where I pinged the patches. My take away is that both
> Gerald and Joseph are fine with the porting, while Sandra has some concerns. Based on her
> feedback, I was able to improve the PDF generated output significantly and I'm pleased by the
> provided feedback. That led to the following 2 Sphinx pulls requests that need to be merged
> before we can migrate the documentation: [1], [2].
> 
> Since the last time I also made one more round of proofreading and the layout was improved
> (mainly for PDF part). Current version of the documentation can be seen here:
> https://splichal.eu/scripts/sphinx/
> 
> I would like to finish the transition once GCC 12.1 gets released in May/June this year.
> There are still some minor regressions, but overall the Sphinx-based documentation should
> be a significant improvement over what we've got right now.
> 
> Please take this email as urgent call for a feedback!
> 
> Thank you,
> Martin
> 
> [1] https://github.com/sphinx-doc/sphinx/pull/10087
> [2] https://github.com/sphinx-doc/sphinx/pull/10001

Hello.

It's been another 5 months since the last project status update. In order to address some Sandra comments
I had to work with upstream in order to merge a few pull requests. That has been achieved and Sphinx 5.1.0
can built the converted documentation.

What has changed since the last time:
1) I made a couple of proof-reading rounds and the documentation should not contain any significant defects.
2) I used a more responsive HTML template Furo that works nicely on mobile devices as well.
3) Number of Sphinx warnings has been reduced.
4) configure script supports not --with-sphinx-build ([1]) that can be used when Sphinx is installed into pip env.
5) Building Documentation chapter was added to gccint manual ([2]).
6) I made a couple of screenshot that show up how is the docs better ([3], Chapter 1).

I'm not planning sending a patchset as most of the patches would not fit in the email limit, so please fetch the following
branch (the last 2 fixme commits will not be installed):

$ git fetch origin refs/users/marxin/heads/sphinx-v7
$ git checkout FETCH_HEAD

The generated documentation (built from GCC source based on the git branch) can be seen here:
https://splichal.eu/gccsphinx-final/

I would like to merge the documentation during the summer if possible before a bigger changes will land in fall.

Thank you,
Martin

[1] https://splichal.eu/gccsphinx-final/html/install/configuration.html#cmdoption-with-sphinx-build
[2] https://splichal.eu/gccsphinx-final/html/gccint/source-tree-structure-and-build-system/the-gcc-subdirectory/building-documentation.html
[3] https://splichal.eu/scripts/sphinx/demo/_build/latex/demo.pdf