From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from smtp-out1.suse.de (smtp-out1.suse.de [195.135.220.28]) by sourceware.org (Postfix) with ESMTPS id 144053857C60; Fri, 27 Aug 2021 09:31:42 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 144053857C60 Authentication-Results: sourceware.org; dmarc=none (p=none dis=none) header.from=suse.cz Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=suse.cz Received: from imap1.suse-dmz.suse.de (imap1.suse-dmz.suse.de [192.168.254.73]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature ECDSA (P-521) server-digest SHA512) (No client certificate requested) by smtp-out1.suse.de (Postfix) with ESMTPS id 074E222371; Fri, 27 Aug 2021 09:31:41 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_rsa; t=1630056701; h=from:from:reply-to:date:date:message-id:message-id:to:to:cc:cc: mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=n/Eud4seqJjzzSXq0cZ4iE0sU9k8J4Dvt4/CUhM/OeU=; b=pewBIKiyoSep80mVu+d7ktKK8LgtOvyjTIuVMYmStiu1xEGyxhBEfP2fzB+l/n/9K7RiPx wWsDvefNTp5krjEMdHLZGlk93n776c96ck82BNyIcQe9Mg5FErvBX88UPX3sBWmzNWyv9C MIxnv//EJyXjtYWAIjQHCs0hzEUXK+A= DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_ed25519; t=1630056701; h=from:from:reply-to:date:date:message-id:message-id:to:to:cc:cc: mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=n/Eud4seqJjzzSXq0cZ4iE0sU9k8J4Dvt4/CUhM/OeU=; b=J3yB7xoCZmGGO6rbVnV3UCLq12In01p62pOE2fuCVaZgg8Wa/l+Rdgxzfs9ZGvMHRjAns/ kpyo0YTeeJCHVnAQ== Received: from imap1.suse-dmz.suse.de (imap1.suse-dmz.suse.de [192.168.254.73]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature ECDSA (P-521) server-digest SHA512) (No client certificate requested) by imap1.suse-dmz.suse.de (Postfix) with ESMTPS id D3267137C0; Fri, 27 Aug 2021 09:31:40 +0000 (UTC) Received: from dovecot-director2.suse.de ([192.168.254.65]) by imap1.suse-dmz.suse.de with ESMTPSA id N+MBMvywKGEZKgAAGKfGzw (envelope-from ); Fri, 27 Aug 2021 09:31:40 +0000 Message-ID: Date: Fri, 27 Aug 2021 11:31:40 +0200 MIME-Version: 1.0 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:91.0) Gecko/20100101 Thunderbird/91.0.1 Subject: Re: GCC documentation: porting to Sphinx Content-Language: en-US From: =?UTF-8?Q?Martin_Li=c5=a1ka?= To: Arnaud Charlet Cc: GCC Development , gcc-patches@gcc.gnu.org, Joseph Myers References: <8641dc55-5412-fbd7-bafd-13604311f5ad@suse.cz> <5ffe3e32-ece0-a1b4-1fcf-e35177fa80b5@suse.cz> <87489d9a-44e2-411c-3f3a-534d07e78b95@suse.cz> <0866a0ea-c846-ea5e-ac7a-d1c8f106cc45@suse.cz> <20210628102305.GA31328@adacore.com> <20210629155424.GB26232@adacore.com> In-Reply-To: Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 8bit X-Spam-Status: No, score=-5.0 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, KAM_EU, KAM_SHORT, NICE_REPLY_A, SPF_HELO_NONE, SPF_PASS, TXREP autolearn=ham autolearn_force=no version=3.4.4 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on server2.sourceware.org X-BeenThere: gcc@gcc.gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gcc mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 27 Aug 2021 09:31:53 -0000 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