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 3417D3969811; Tue, 10 Aug 2021 15:43:51 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 3417D3969811 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 38D9C2208D; Tue, 10 Aug 2021 15:43:50 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_rsa; t=1628610230; 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=G3/o7X3XpWyTcQjSnCDZspjZreisws5y9OYDYl60RbI=; b=DDTX2Z7kpDxwJJdAUtVp4o0YND/VVNR4Fjmtf/RTi45xMgCD5QItbmtJ6ulb/WkuZT2I0S QBUsX2yiPaZ7ZU4X/pRQr0gyMLcEPiIaliOUvZv518uxtz2MjXcuJt6lUXjAfmobqeCk4G rEVbn7sKWExppKcb8L7CBV3OQXj7DJ8= DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_ed25519; t=1628610230; 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=G3/o7X3XpWyTcQjSnCDZspjZreisws5y9OYDYl60RbI=; b=eweEyVjzS3mMlZS7jN6HFJrySlSxXuMh6Q5GIZ1gQG374SVkCcZZr24LaDg4+djcNIusAg UiATIbs7Z0EhkrDg== 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 0C069137DA; Tue, 10 Aug 2021 15:43:50 +0000 (UTC) Received: from dovecot-director2.suse.de ([192.168.254.65]) by imap1.suse-dmz.suse.de with ESMTPSA id eEtMAbaeEmHSRwAAGKfGzw (envelope-from ); Tue, 10 Aug 2021 15:43:50 +0000 From: =?UTF-8?Q?Martin_Li=c5=a1ka?= Subject: Re: GCC documentation: porting to Sphinx To: Arnaud Charlet Cc: Joseph Myers , GCC Development , gcc-patches@gcc.gnu.org, David Malcolm , Richard Biener , Gerald Pfeifer 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> Message-ID: Date: Tue, 10 Aug 2021 17:43:49 +0200 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:78.0) Gecko/20100101 Thunderbird/78.12.0 MIME-Version: 1.0 In-Reply-To: Content-Type: text/plain; charset=utf-8; format=flowed Content-Language: en-US Content-Transfer-Encoding: 8bit X-Spam-Status: No, score=-4.4 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=no 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: Tue, 10 Aug 2021 15:44:01 -0000 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 Generated output (directly made from GCC source tree) can be seen here: https://splichal.eu/gccsphinx-final/ 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 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 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