[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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



On Fri, 2 Jul 2021, Luca Fancellu wrote:
> > On 1 Jul 2021, at 18:43, Stefano Stabellini <sstabellini@xxxxxxxxxx> wrote:
> > 
> > On Thu, 1 Jul 2021, Luca Fancellu wrote:
> >>> On 24 Jun 2021, at 00:33, Stefano Stabellini <sstabellini@xxxxxxxxxx> 
> >>> 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@xxxxxxx>
> >>>> ---
> >>>> .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.

 


Rackspace

Lists.xenproject.org is hosted with RackSpace, monitoring our
servers 24x7x365 and backed by RackSpace's Fanatical Support®.