Re: [PATCH v6 7/9] docs: Change Makefile and sphinx configuration for doxygen

From: Luca Fancellu <luca.fancellu@arm.com>
To: Stefano Stabellini <sstabellini@kernel.org>
Cc: xen-devel@lists.xenproject.org,
	Bertrand Marquis <bertrand.marquis@arm.com>,
	wei.chen@arm.com, Andrew Cooper <andrew.cooper3@citrix.com>,
	George Dunlap <george.dunlap@citrix.com>,
	Ian Jackson <iwj@xenproject.org>, Jan Beulich <jbeulich@suse.com>,
	Julien Grall <julien@xen.org>, Wei Liu <wl@xen.org>
Subject: Re: [PATCH v6 7/9] docs: Change Makefile and sphinx configuration for doxygen
Date: Mon, 5 Jul 2021 10:41:13 +0100	[thread overview]
Message-ID: <9C2F15B2-2B24-4C23-9902-8FE355C01201@arm.com> (raw)
In-Reply-To: <alpine.DEB.2.21.2107021324090.9437@sstabellini-ThinkPad-T480s>

> On 2 Jul 2021, at 23:23, Stefano Stabellini <sstabellini@kernel.org> wrote:
> 
> On Fri, 2 Jul 2021, Luca Fancellu wrote:
>>> On 1 Jul 2021, at 18:43, Stefano Stabellini <sstabellini@kernel.org> wrote:
>>> 
>>> On Thu, 1 Jul 2021, Luca Fancellu wrote:
>>>>> On 24 Jun 2021, at 00:33, Stefano Stabellini <sstabellini@kernel.org> 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 <luca.fancellu@arm.com>
>>>>>> ---
>>>>>> .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?
> 

Hi Stefano,

> I totally missed patches 4 and 5. Can you please CC me to the whole
> series next time?

Yes, I think the script add_maintainers.pl didn’t add you in CC on these patches, for the next version I will add you manually

Cheers,

Luca

> 
> 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.