Revert Sphinx documentation [Was: Issues with Sphinx]

Revert Sphinx documentation [Was: Issues with Sphinx]

[Martin Liška]

Hi.

The situation with the Sphinx migration went out of control. The TODO list
overwhelmed me and there are road-blocks that can't be easily fixed with what
Sphinx currently supports. That would require addition of an upstream support and
a possible new Sphinx release.

Let me summarize the biggest road blocks:

1) PR107634 - documentation is divided among much files than it used to be; plus
   the current filenames tend to be very long
2) Index page regressions: PR107643 and PR107651
3) PR107656 - c::macro and c::function does replace [Macro:], [Target Hook:] well
4) Makefile.am, build system issues: missing support for lib*/Makefile.am and various
   limitation when it comes to 'make install-*'. Moreover, gcc_release --enable-generated-files-in-srcdir
   is not supported yet.

Plus, there are other issues linked in PR107655 and we face the issue that
many web links (to GCC documentation) are in the wild and should not become 404.

I would like to apologize to anybody who wasted a time with adoption to the Sphinx format
which we be reverted eventually. Special thanks belongs to all people who helped me and
prepared various patches.

I'm going to revert the patchset during today (Monday) and I'll send a patch with a couple
of new changes that landed in the period of time we used Sphinx.

Thank you for your understanding.
Martin

Re: Revert Sphinx documentation [Was: Issues with Sphinx]

[Martin Liška]

On 11/14/22 03:49, Martin Liška wrote:
> I'm going to revert the patchset during today (Monday) and I'll send a patch with a couple
> of new changes that landed in the period of time we used Sphinx.

The revert is done and I included ce51e8439a491910348a1c5aea43b55f000ba8ac commit
that ports all the new documentation bits to Texinfo.

Web pages content will be updated with Jakub in the afternoon.

Martin

Re: Revert Sphinx documentation [Was: Issues with Sphinx]

[Jonathan Wakely]

[-- Attachment #1: Type: text/plain, Size: 824 bytes --]

On Mon, 14 Nov 2022 at 08:40, Martin Liška wrote:
>
> On 11/14/22 03:49, Martin Liška wrote:
> > I'm going to revert the patchset during today (Monday) and I'll send a patch with a couple
> > of new changes that landed in the period of time we used Sphinx.
>
> The revert is done and I included ce51e8439a491910348a1c5aea43b55f000ba8ac commit
> that ports all the new documentation bits to Texinfo.

Sorry it didn't work out, and thanks for reapplying my two doc changes
that landed during the era of the sphinx.

I formatted my new region/endregion pragmas on one line because that
seemed to be how it should be done for rSt, e.g. we had:

``#pragma GCC push_options`` ``#pragma GCC pop_options``

But I think the attached patch is more correct for how we document
pragmas in texinfo.

OK for trunk?

[-- Attachment #2: patch.txt --]
[-- Type: text/plain, Size: 973 bytes --]

commit 3aa461d4ba46449544730a342cb2dcb0ce6851e9
Author: Jonathan Wakely <jwakely@redhat.com>
Date:   Mon Nov 14 09:19:13 2022

    doc: Format region pragmas as separate items
    
    This seems consistent with how other paired pragmas are documented in
    texinfo, e.g. push_options and pop_options.
    
    gcc/ChangeLog:
    
            * doc/cpp.texi (Pragmas): Use @item and @itemx for region
            pragmas.

diff --git a/gcc/doc/cpp.texi b/gcc/doc/cpp.texi
index 1be29eb605e..5e86a957a88 100644
--- a/gcc/doc/cpp.texi
+++ b/gcc/doc/cpp.texi
@@ -3843,7 +3843,8 @@ file will never be read again, no matter what.  It is a less-portable
 alternative to using @samp{#ifndef} to guard the contents of header files
 against multiple inclusions.
 
-@code{#pragma region @{tokens@}...}, @code{#pragma endregion @{tokens@}...}
+@item #pragma region @{tokens@}...
+@itemx #pragma endregion @{tokens@}...
 These pragmas are accepted, but have no effect.
 
 @end ftable

Re: Revert Sphinx documentation [Was: Issues with Sphinx]

[Gerald Pfeifer]

[-- Attachment #1: Type: text/plain, Size: 924 bytes --]

On Mon, 14 Nov 2022, Martin Liška wrote:
> The situation with the Sphinx migration went out of control. The TODO 
> list overwhelmed me and there are road-blocks that can't be easily fixed 
> with what Sphinx currently supports.

This migration was/is a huge and complex undertaking, and you have been 
patiently chipping away at obstacle after obstacle.

So while it probably is disappointing it did not go through this time,
you made a lot of progress and important contributions - and we all 
learned quite a bit more, also in terms of (not so obvious) requirements,
dependencies, and road blocks left which you summarized.


Timing was tricky for me being on the road last week and I am definitely
committed to keep helping with this transition. Maybe soon after we are in 
stage 1 again?

And would it make sense to convert at least our installation docs and
https://gcc.gnu.org/install/ for the GCC 13 release?

Gerald

Re: Revert Sphinx documentation [Was: Issues with Sphinx]

[Gerald Pfeifer]

On Mon, 14 Nov 2022, Jonathan Wakely wrote:
> I formatted my new region/endregion pragmas on one line because that
> seemed to be how it should be done for rSt, e.g. we had:
> 
> ``#pragma GCC push_options`` ``#pragma GCC pop_options``
> 
> But I think the attached patch is more correct for how we document
> pragmas in texinfo.
> 
> OK for trunk?

Looks good to my eyes. Thank you for caring for such details, Jonathan!

Gerald

Re: Revert Sphinx documentation [Was: Issues with Sphinx]

[Martin Liška]

On 11/14/22 14:06, Gerald Pfeifer wrote:
> On Mon, 14 Nov 2022, Martin Liška wrote:
>> The situation with the Sphinx migration went out of control. The TODO 
>> list overwhelmed me and there are road-blocks that can't be easily fixed 
>> with what Sphinx currently supports.
> 
> This migration was/is a huge and complex undertaking, and you have been 
> patiently chipping away at obstacle after obstacle.
> 
> So while it probably is disappointing it did not go through this time,
> you made a lot of progress and important contributions - and we all 
> learned quite a bit more, also in terms of (not so obvious) requirements,
> dependencies, and road blocks left which you summarized.

Hello.

I see it similarly and I'm trying to take the best out of it.

> 
> 
> Timing was tricky for me being on the road last week and I am definitely
> committed to keep helping with this transition. Maybe soon after we are in 
> stage 1 again?

For now, I'm not planning working on that in the future. Maybe, someone else
can carry on working on that.

> 
> And would it make sense to convert at least our installation docs and
> https://gcc.gnu.org/install/ for the GCC 13 release?

Yes, it's definitely doable as it's quite small, not split among too many .rst
files and the HTML version is mainly built at our server in order to populate
gcc.gnu.org/install

I'm willing to help anybody, but it won't be me who will suggest/send
the patches.

Thanks for understanding.
Martin

> 
> Gerald