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