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=-17.9 required=3.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,INCLUDES_CR_TRAILER,INCLUDES_PATCH, MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED,USER_AGENT_SANE_1 autolearn=ham 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 465C9C07E97 for ; Fri, 2 Jul 2021 22:23:19 +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 0CB10613D8 for ; Fri, 2 Jul 2021 22:23:19 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 0CB10613D8 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.149354.276160 (Exim 4.92) (envelope-from ) id 1lzRZ2-0001XW-02; Fri, 02 Jul 2021 22:23:12 +0000 X-Outflank-Mailman: Message body and most headers restored to incoming version Received: by outflank-mailman (output) from mailman id 149354.276160; Fri, 02 Jul 2021 22:23:11 +0000 Received: from localhost ([127.0.0.1] helo=lists.xenproject.org) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1lzRZ1-0001XN-So; Fri, 02 Jul 2021 22:23:11 +0000 Received: by outflank-mailman (input) for mailman id 149354; Fri, 02 Jul 2021 22:23:10 +0000 Received: from all-amaz-eas1.inumbo.com ([34.197.232.57] helo=us1-amaz-eas2.inumbo.com) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1lzRYz-0001TB-UK for xen-devel@lists.xenproject.org; Fri, 02 Jul 2021 22:23:09 +0000 Received: from mail.kernel.org (unknown [198.145.29.99]) by us1-amaz-eas2.inumbo.com (Halon) with ESMTPS id 142bdc0a-db84-11eb-83c9-12813bfff9fa; Fri, 02 Jul 2021 22:23:08 +0000 (UTC) Received: by mail.kernel.org (Postfix) with ESMTPSA id F1AD5613D8; Fri, 2 Jul 2021 22:23:07 +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: 142bdc0a-db84-11eb-83c9-12813bfff9fa DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1625264588; bh=zQNj7JPmp8LSW80+gBSqlEodeUICaVTJJkxXZfv6L2I=; h=Date:From:To:cc:Subject:In-Reply-To:References:From; b=BirKJ1REFub07HLbB102mTrRvf8LWj3y34qKXKdfeNv4zLO3NJtweDeDVYvBVWlRV fpoOzRlon/BvfeSwbTKQu3v9Ko5/uajP43/awOp4pMtVDkhRettlJqudcCSkrOaZmY rMCDfY2enO3AkhqoKi66jH61G+PfkLZrtfvSAvmAXvxNGiu7ioCwvNlMnxY7L/YIIN jimb94yZV4k75ZjwtsrbYm6C5BdPrltfCp4yHQNAzz14gps9wLOrPHCtl3DGQQLyE/ KV2iXxdhujkkaJ7V4UJYqRnA4ZvoyQLvoLgraiIA3XH1bPm93Ddccx8LhCP5c0CBbq XYjoY9WHI21iQ== Date: Fri, 2 Jul 2021 15:23:07 -0700 (PDT) From: Stefano Stabellini X-X-Sender: sstabellini@sstabellini-ThinkPad-T480s To: Luca Fancellu cc: Stefano Stabellini , xen-devel@lists.xenproject.org, Bertrand Marquis , wei.chen@arm.com, Andrew Cooper , George Dunlap , Ian Jackson , Jan Beulich , Julien Grall , Wei Liu Subject: Re: [PATCH v6 7/9] docs: Change Makefile and sphinx configuration for doxygen In-Reply-To: <7C3269F1-3C61-4F39-82F9-9DE4C563849B@arm.com> Message-ID: References: <20210510084105.17108-1-luca.fancellu@arm.com> <20210510084105.17108-8-luca.fancellu@arm.com> <1FC1E8DF-8AED-4ABD-BE9A-DBBD9D66EDBB@arm.com> <7C3269F1-3C61-4F39-82F9-9DE4C563849B@arm.com> User-Agent: Alpine 2.21 (DEB 202 2017-01-01) MIME-Version: 1.0 Content-Type: multipart/mixed; BOUNDARY="8323329-766106159-1625257521=:9437" Content-ID: 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-766106159-1625257521=:9437 Content-Type: text/plain; CHARSET=UTF-8 Content-Transfer-Encoding: 8BIT Content-ID: On Fri, 2 Jul 2021, Luca Fancellu wrote: > > On 1 Jul 2021, at 18:43, Stefano Stabellini wrote: > > > > On Thu, 1 Jul 2021, Luca Fancellu wrote: > >>> On 24 Jun 2021, at 00:33, Stefano Stabellini wrote: > >>> > >>> On Mon, 10 May 2021, Luca Fancellu wrote: > >>>> Modify docs/Makefile to call doxygen and generate sphinx > >>>> html documentation given the doxygen XML output. > >>>> > >>>> Modify docs/conf.py sphinx configuration file to setup > >>>> the breathe extension that works as bridge between > >>>> sphinx and doxygen. > >>>> > >>>> Add some files to the .gitignore to ignore some > >>>> generated files for doxygen. > >>>> > >>>> Signed-off-by: Luca Fancellu > >>>> --- > >>>> .gitignore | 6 ++++++ > >>>> docs/Makefile | 42 +++++++++++++++++++++++++++++++++++++++--- > >>>> docs/conf.py | 48 +++++++++++++++++++++++++++++++++++++++++++++--- > >>>> 3 files changed, 90 insertions(+), 6 deletions(-) > >>>> > >>>> diff --git a/.gitignore b/.gitignore > >>>> index 1c2fa1530b..d271e0ce6a 100644 > >>>> --- a/.gitignore > >>>> +++ b/.gitignore > >>>> @@ -58,6 +58,12 @@ docs/man7/ > >>>> docs/man8/ > >>>> docs/pdf/ > >>>> docs/txt/ > >>>> +docs/doxygen-output > >>>> +docs/sphinx > >>>> +docs/xen.doxyfile > >>>> +docs/xen.doxyfile.tmp > >>>> +docs/xen-doxygen/doxygen_include.h > >>>> +docs/xen-doxygen/doxygen_include.h.tmp > >>>> extras/mini-os* > >>>> install/* > >>>> stubdom/*-minios-config.mk > >>>> diff --git a/docs/Makefile b/docs/Makefile > >>>> index 8de1efb6f5..2f784c36ce 100644 > >>>> --- a/docs/Makefile > >>>> +++ b/docs/Makefile > >>>> @@ -17,6 +17,18 @@ TXTSRC-y := $(sort $(shell find misc -name '*.txt' -print)) > >>>> > >>>> PANDOCSRC-y := $(sort $(shell find designs/ features/ misc/ process/ specs/ \( -name '*.pandoc' -o -name '*.md' \) -print)) > >>>> > >>>> +# Directory in which the doxygen documentation is created > >>>> +# This must be kept in sync with breathe_projects value in conf.py > >>>> +DOXYGEN_OUTPUT = doxygen-output > >>>> + > >>>> +# Doxygen input headers from xen-doxygen/doxy_input.list file > >>>> +DOXY_LIST_SOURCES != cat "xen-doxygen/doxy_input.list" > >>>> +DOXY_LIST_SOURCES := $(realpath $(addprefix $(XEN_ROOT)/,$(DOXY_LIST_SOURCES))) > >> > >> Hi Stefano, > >> > >>> > >>> I cannot find exactly who is populating doxy_input.list. I can see it is > >>> empty in patch #6. Does it get populated during the build? > >> > >> doxy_input.list is the only file that should be modified by the developer when he/she wants to add documentation > >> for a new file to be parsed by Doxygen, in my patch about documenting grant_tables.h you can see I add > >> there the path “xen/include/public/grant_table.h" > > > > OK, thanks. I missed that addition. > > > > > >>> > >>>> +DOXY_DEPS := xen.doxyfile \ > >>>> + xen-doxygen/mainpage.md \ > >>>> + xen-doxygen/doxygen_include.h > >>>> + > >>>> # Documentation targets > >>>> $(foreach i,$(MAN_SECTIONS), \ > >>>> $(eval DOC_MAN$(i) := $(patsubst man/%.$(i),man$(i)/%.$(i), \ > >>>> @@ -46,8 +58,28 @@ all: build > >>>> build: html txt pdf man-pages figs > >>>> > >>>> .PHONY: sphinx-html > >>>> -sphinx-html: > >>>> - sphinx-build -b html . sphinx/html > >>>> +sphinx-html: $(DOXY_DEPS) $(DOXY_LIST_SOURCES) > >>>> +ifneq ($(SPHINXBUILD),no) > >>> > >>> This check on SPHINXBUILD is new, it wasn't there before. Why do we need > >>> it now? We are not really changing anything in regards to Sphinx, just > >>> adding Doxygen support. Or was it a mistake that it was missing even > >>> before this patch? > >> > >> Yes this is new, I saw that we didn’t look if sphinx was installed in the system, so now we did > > > > In that case, I think anything related to SPHINXBUILD and whether sphinx > > is installed or not, should be a separate patch at the beginning of the > > series. It could be committed independently before the rest of the > > series. When we get to this patch, SPHINXBUILD should be already there. > > I’ve introduced SPHINXBUILD in this patch: [PATCH v6 5/9] docs: add checks to configure for sphinx and doxygen, > In your commend do you mean that you would like it to be outside this serie and this serie to be based on top of that one? I totally missed patches 4 and 5. Can you please CC me to the whole series next time? I meant as a separate patch, like you have done in patch #5. It doesn't necessarily need to be at the beginning of the series so what you have already done is OK. --8323329-766106159-1625257521=:9437--