From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-7.5 required=3.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,MAILING_LIST_MULTI,SPF_HELO_NONE, SPF_PASS,USER_AGENT_SANE_1 autolearn=no autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id B6FADC433ED for ; Tue, 6 Apr 2021 21:25:21 +0000 (UTC) Received: from lists.xenproject.org (lists.xenproject.org [192.237.175.120]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id 6658061396 for ; Tue, 6 Apr 2021 21:25:21 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 6658061396 Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=kernel.org Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=xen-devel-bounces@lists.xenproject.org Received: from list by lists.xenproject.org with outflank-mailman.106307.203312 (Exim 4.92) (envelope-from ) id 1lTtBv-0006au-PB; Tue, 06 Apr 2021 21:24:55 +0000 X-Outflank-Mailman: Message body and most headers restored to incoming version Received: by outflank-mailman (output) from mailman id 106307.203312; Tue, 06 Apr 2021 21:24:55 +0000 Received: from localhost ([127.0.0.1] helo=lists.xenproject.org) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1lTtBv-0006an-MG; Tue, 06 Apr 2021 21:24:55 +0000 Received: by outflank-mailman (input) for mailman id 106307; Tue, 06 Apr 2021 21:24:54 +0000 Received: from us1-rack-iad1.inumbo.com ([172.99.69.81]) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1lTtBu-0006ai-Aq for xen-devel@lists.xenproject.org; Tue, 06 Apr 2021 21:24:54 +0000 Received: from mail.kernel.org (unknown [198.145.29.99]) by us1-rack-iad1.inumbo.com (Halon) with ESMTPS id 31548986-699d-460f-96da-b1d3b419f200; Tue, 06 Apr 2021 21:24:53 +0000 (UTC) Received: by mail.kernel.org (Postfix) with ESMTPSA id A2DB461396; Tue, 6 Apr 2021 21:24:52 +0000 (UTC) X-BeenThere: xen-devel@lists.xenproject.org List-Id: Xen developer discussion List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Errors-To: xen-devel-bounces@lists.xenproject.org Precedence: list Sender: "Xen-devel" X-Inumbo-ID: 31548986-699d-460f-96da-b1d3b419f200 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1617744293; bh=H2NAWP4Xi7y6EV5xHX1I9+POqLpf99goDaZ8lVmFaUY=; h=Date:From:To:cc:Subject:In-Reply-To:References:From; b=Y5Pg0fHm1ZX8R7Chj0E/JZOkd2eoNizyOWV7mtVOYMw4aUS5YsPh95t223j9oOYUU DoVow/TjAx6cn9PumcJFQLfx8+aoqFbzdArT8CXcv07La3+k/CVSBA0XPrdddQ5NP6 pY5uXFzhq0+4I+OOzHnKpeO2BOx+I8Q0iCEVTmofhXcWs0AXRjK5Mu4WNsDLBEDwJv TeCKtnupt5H6JfVLwh0QuatqnTwcFUXIh6DvRaC43QC3eBdVVT50g6AXaz/qOoeesB qCcJQqyl4tN/UUGT9nX5Wh3fwDrv8yV8WV9Um/8cvkT0E4LGaF18vYUzSI6aAWfgHf bd8O5VlCZMfmg== Date: Tue, 6 Apr 2021 14:24:51 -0700 (PDT) From: Stefano Stabellini X-X-Sender: sstabellini@sstabellini-ThinkPad-T480s To: Andrew Cooper cc: Luca Fancellu , xen-devel@lists.xenproject.org, bertrand.marquis@arm.com, wei.chen@arm.com, George Dunlap , Ian Jackson , Jan Beulich , Julien Grall , Stefano Stabellini , Wei Liu Subject: Re: [PATCH 0/3] Use Doxygen and sphinx for html documentation In-Reply-To: <225d7e0a-c5c6-a954-9141-ba1d859f400a@citrix.com> Message-ID: References: <20210406103603.8530-1-luca.fancellu@arm.com> <225d7e0a-c5c6-a954-9141-ba1d859f400a@citrix.com> User-Agent: Alpine 2.21 (DEB 202 2017-01-01) MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="8323329-285525972-1617744292=:31460" This message is in MIME format. The first part should be readable text, while the remaining parts are likely unreadable without MIME-aware tools. --8323329-285525972-1617744292=:31460 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8BIT On Tue, 6 Apr 2021, Andrew Cooper wrote: > On 06/04/2021 11:36, Luca Fancellu wrote: > > This serie introduce doxygen in the sphinx html docs generation. > > One benefit is to keep most of the documentation in the source > > files of xen so that it's more maintainable, on the other hand > > there are some limitation of doxygen that must be addressed > > modifying the current codebase (for example doxygen can't parse > > anonymous structure/union). > > > > To reproduce the documentation xen must be compiled because > > most of the headers are generated on compilation time from > > the makefiles. > > > > Here follows the steps to generate the sphinx html docs, some > > package may be required on your machine, everything is suggested > > by the autoconf script. > > Here I'm building the arm64 docs (the only introduced for now by > > this serie): > > > > ./configure > > make -C xen XEN_TARGET_ARCH="arm64" CROSS_COMPILE="aarch64-linux-gnu-" menuconfig > > make -C xen XEN_TARGET_ARCH="arm64" CROSS_COMPILE="aarch64-linux-gnu-" > > make -C docs XEN_TARGET_ARCH="arm64" sphinx-html > > > > now in docs/sphinx/html/ we have the generated docs starting > > from the index.html page. > > Do you have a sample rendered output? > > The plan was to try and use Linux's kernel-doc plugin for Sphinx, which > is very doxygen-like.  Did you experiment with this option? As you probably know the end goal for Luca (and the Xen FuSa SIG as a whole) is to generate all FuSa documents, including requirements docs, interface docs, etc. FuSa requires us to follow the famous V model, where the high level requirements are linked to the lower level requirements, which are linked to the interface docs, which are linked all the way down to the code. Maintaining the linking is difficult and typically done with expensive proprietary FuSa tools. Fortunately, an engineer working with the Zephyr project developed a set of scripts for Doxygen that are able to generate the required FuSa docs and also links from in-code comments and markdown/rst docs in the tree. This is great work, and in the FuSa SIG we thought it would be best to align ourselves with Zephyr to be able to pull our efforts together on the tooling side instead of doing the same thing again on our own. This is the reason why we ended up with Doxygen. --8323329-285525972-1617744292=:31460--