* Revert Sphinx documentation [Was: Issues with Sphinx] [not found] <CA+=Sn1m=F6JVszrTFS_v=rfC7nrO=X5pSbgestxtPr___QGQuA@mail.gmail.com> @ 2022-11-14 2:49 ` Martin Liška 2022-11-14 8:38 ` Martin Liška 2022-11-14 13:06 ` Gerald Pfeifer 0 siblings, 2 replies; 6+ messages in thread From: Martin Liška @ 2022-11-14 2:49 UTC (permalink / raw) To: Andrew Pinski, GCC Mailing List; +Cc: GCC Patches 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 ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: Revert Sphinx documentation [Was: Issues with Sphinx] 2022-11-14 2:49 ` Revert Sphinx documentation [Was: Issues with Sphinx] Martin Liška @ 2022-11-14 8:38 ` Martin Liška 2022-11-14 9:24 ` Jonathan Wakely 2022-11-14 13:06 ` Gerald Pfeifer 1 sibling, 1 reply; 6+ messages in thread From: Martin Liška @ 2022-11-14 8:38 UTC (permalink / raw) To: Andrew Pinski, GCC Mailing List; +Cc: GCC Patches, Gerald Pfeifer 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 ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: Revert Sphinx documentation [Was: Issues with Sphinx] 2022-11-14 8:38 ` Martin Liška @ 2022-11-14 9:24 ` Jonathan Wakely 2022-11-14 22:26 ` Gerald Pfeifer 0 siblings, 1 reply; 6+ messages in thread From: Jonathan Wakely @ 2022-11-14 9:24 UTC (permalink / raw) To: Martin Liška Cc: Andrew Pinski, GCC Mailing List, GCC Patches, Gerald Pfeifer [-- 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 ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: Revert Sphinx documentation [Was: Issues with Sphinx] 2022-11-14 9:24 ` Jonathan Wakely @ 2022-11-14 22:26 ` Gerald Pfeifer 0 siblings, 0 replies; 6+ messages in thread From: Gerald Pfeifer @ 2022-11-14 22:26 UTC (permalink / raw) To: Jonathan Wakely Cc: Martin Liška, Andrew Pinski, GCC Mailing List, GCC Patches 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 ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: Revert Sphinx documentation [Was: Issues with Sphinx] 2022-11-14 2:49 ` Revert Sphinx documentation [Was: Issues with Sphinx] Martin Liška 2022-11-14 8:38 ` Martin Liška @ 2022-11-14 13:06 ` Gerald Pfeifer 2022-11-15 10:05 ` Martin Liška 1 sibling, 1 reply; 6+ messages in thread From: Gerald Pfeifer @ 2022-11-14 13:06 UTC (permalink / raw) To: Martin Liška; +Cc: Andrew Pinski, gcc, gcc-patches [-- 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 ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: Revert Sphinx documentation [Was: Issues with Sphinx] 2022-11-14 13:06 ` Gerald Pfeifer @ 2022-11-15 10:05 ` Martin Liška 0 siblings, 0 replies; 6+ messages in thread From: Martin Liška @ 2022-11-15 10:05 UTC (permalink / raw) To: Gerald Pfeifer; +Cc: Andrew Pinski, gcc, gcc-patches 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 ^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2022-11-15 10:05 UTC | newest] Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- [not found] <CA+=Sn1m=F6JVszrTFS_v=rfC7nrO=X5pSbgestxtPr___QGQuA@mail.gmail.com> 2022-11-14 2:49 ` Revert Sphinx documentation [Was: Issues with Sphinx] Martin Liška 2022-11-14 8:38 ` Martin Liška 2022-11-14 9:24 ` Jonathan Wakely 2022-11-14 22:26 ` Gerald Pfeifer 2022-11-14 13:06 ` Gerald Pfeifer 2022-11-15 10:05 ` Martin Liška
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).