xen-devel.lists.xenproject.org archive mirror
 help / color / mirror / Atom feed
From: Stefano Stabellini <sstabellini@kernel.org>
To: Luca Fancellu <luca.fancellu@arm.com>
Cc: Stefano Stabellini <sstabellini@kernel.org>,
	 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: Fri, 2 Jul 2021 15:23:07 -0700 (PDT)	[thread overview]
Message-ID: <alpine.DEB.2.21.2107021324090.9437@sstabellini-ThinkPad-T480s> (raw)
In-Reply-To: <7C3269F1-3C61-4F39-82F9-9DE4C563849B@arm.com>

[-- Attachment #1: Type: text/plain, Size: 4521 bytes --]

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?

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.

  reply	other threads:[~2021-07-02 22:23 UTC|newest]

Thread overview: 30+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-05-10  8:40 [PATCH v6 0/9] Use Doxygen and sphinx for html documentation Luca Fancellu
2021-05-10  8:40 ` [PATCH v6 1/9] docs: add doxygen configuration file Luca Fancellu
2021-05-10  8:40 ` [PATCH v6 2/9] docs: add Xen png logo for the doxygen documentation Luca Fancellu
2021-05-10  8:40 ` [PATCH v6 3/9] docs: add doxygen templates Luca Fancellu
2021-05-10  8:41 ` [PATCH v6 4/9] m4/python: add function to docs_tool.m4 and new m4 module Luca Fancellu
2021-07-02 22:22   ` Stefano Stabellini
2021-05-10  8:41 ` [PATCH v6 5/9] docs: add checks to configure for sphinx and doxygen Luca Fancellu
2021-07-02 22:22   ` Stefano Stabellini
2021-05-10  8:41 ` [PATCH v6 6/9] docs: add doxygen preprocessor and related files Luca Fancellu
2021-06-23 22:03   ` Stefano Stabellini
2021-07-01 13:04     ` Luca Fancellu
2021-07-01 17:36       ` Stefano Stabellini
2021-05-10  8:41 ` [PATCH v6 7/9] docs: Change Makefile and sphinx configuration for doxygen Luca Fancellu
2021-06-23 23:33   ` Stefano Stabellini
2021-07-01 13:36     ` Luca Fancellu
2021-07-01 17:43       ` Stefano Stabellini
2021-07-02  9:30         ` Luca Fancellu
2021-07-02 22:23           ` Stefano Stabellini [this message]
2021-07-05  9:41             ` Luca Fancellu
2021-05-10  8:41 ` [PATCH v6 8/9] docs: hypercalls sphinx skeleton for generated html Luca Fancellu
2021-06-23 23:34   ` Stefano Stabellini
2021-07-01 14:06     ` Luca Fancellu
2021-07-01 17:24       ` Stefano Stabellini
2021-05-10  8:41 ` [PATCH v6 9/9] docs/doxygen: doxygen documentation for grant_table.h Luca Fancellu
2021-06-23 23:34   ` Stefano Stabellini
2021-07-01 14:19     ` Luca Fancellu
2021-07-01 17:44       ` Stefano Stabellini
2021-07-02 11:01         ` Luca Fancellu
2021-07-02 20:21           ` Stefano Stabellini
2021-06-07 16:24 ` [PATCH v6 0/9] Use Doxygen and sphinx for html documentation Luca Fancellu

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=alpine.DEB.2.21.2107021324090.9437@sstabellini-ThinkPad-T480s \
    --to=sstabellini@kernel.org \
    --cc=andrew.cooper3@citrix.com \
    --cc=bertrand.marquis@arm.com \
    --cc=george.dunlap@citrix.com \
    --cc=iwj@xenproject.org \
    --cc=jbeulich@suse.com \
    --cc=julien@xen.org \
    --cc=luca.fancellu@arm.com \
    --cc=wei.chen@arm.com \
    --cc=wl@xen.org \
    --cc=xen-devel@lists.xenproject.org \
    --subject='Re: [PATCH v6 7/9] docs: Change Makefile and sphinx configuration for doxygen' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).