|
[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 2 Jul 2021, at 23:23, Stefano Stabellini <sstabellini@xxxxxxxxxx> wrote: > > 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? > 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.
|
 |
Lists.xenproject.org is hosted with RackSpace, monitoring our |