From nobody Sat Nov 30 02:53:06 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of lists.xenproject.org designates 192.237.175.120 as permitted sender) client-ip=192.237.175.120; envelope-from=xen-devel-bounces@lists.xenproject.org; helo=lists.xenproject.org; Authentication-Results: mx.zohomail.com; spf=pass (zohomail.com: domain of lists.xenproject.org designates 192.237.175.120 as permitted sender) smtp.mailfrom=xen-devel-bounces@lists.xenproject.org; dmarc=fail(p=none dis=none) header.from=arm.com ARC-Seal: i=1; a=rsa-sha256; t=1620636218; cv=none; d=zohomail.com; s=zohoarc; b=cTv1Go6tHoo4ia2ikZ8vIA3DmORKn+9hG6vUA0lYQgQ9lwFqlZCVDmWJZ5vsd7fk+pJ0Qm5QILe08pel0mrzGtjcp6ewXEgxI8F9wgr6Fjo5axfSvNEtS51ItJHk9IICzTBKfIgywMaGKahxj2ULh4ExTpxTsQdKHdzdOVLTLps= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1620636218; h=Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Help:List-Unsubscribe:Message-ID:References:Sender:Subject:To; bh=0VcbZHoiPZ4uIhbrdSIBJlTgxwJqn0jv06RweYoxIsw=; b=GQ3nu/e5qMO6SLOuvgcf7kphku59uv3CpceNoXyz+2URouLxCu9jw3bwnGZC/FhFIHVSXw3H+5LGPcTm57bMAJ3o61qsHZmrKZMXqiUeYkbjenK7gbhQDTi7+z6InXh8MdxwBP8uDbrDtUK6SXPqjUWm/vtzDZ8brxUQ5qZT9nM= ARC-Authentication-Results: i=1; mx.zohomail.com; spf=pass (zohomail.com: domain of lists.xenproject.org designates 192.237.175.120 as permitted sender) smtp.mailfrom=xen-devel-bounces@lists.xenproject.org; dmarc=fail header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.xenproject.org (lists.xenproject.org [192.237.175.120]) by mx.zohomail.com with SMTPS id 162063621887095.82185194235456; Mon, 10 May 2021 01:43:38 -0700 (PDT) Received: from list by lists.xenproject.org with outflank-mailman.124999.235358 (Exim 4.92) (envelope-from ) id 1lg1Ve-0005yE-4f; Mon, 10 May 2021 08:43:26 +0000 Received: by outflank-mailman (output) from mailman id 124999.235358; Mon, 10 May 2021 08:43:26 +0000 Received: from localhost ([127.0.0.1] helo=lists.xenproject.org) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1lg1Ve-0005x2-0s; Mon, 10 May 2021 08:43:26 +0000 Received: by outflank-mailman (input) for mailman id 124999; Mon, 10 May 2021 08:43:24 +0000 Received: from us1-rack-iad1.inumbo.com ([172.99.69.81]) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1lg1U6-0008L0-OP for xen-devel@lists.xenproject.org; Mon, 10 May 2021 08:41:50 +0000 Received: from foss.arm.com (unknown [217.140.110.172]) by us1-rack-iad1.inumbo.com (Halon) with ESMTP id e9f42ebd-eb64-47a7-a2ce-c4d9b87a9826; Mon, 10 May 2021 08:41:25 +0000 (UTC) Received: from usa-sjc-imap-foss1.foss.arm.com (unknown [10.121.207.14]) by usa-sjc-mx-foss1.foss.arm.com (Postfix) with ESMTP id 2FB6C1424; Mon, 10 May 2021 01:41:25 -0700 (PDT) Received: from e125770.cambridge.arm.com (e125770.cambridge.arm.com [10.1.197.16]) by usa-sjc-imap-foss1.foss.arm.com (Postfix) with ESMTPSA id BE41A3F719; Mon, 10 May 2021 01:41:23 -0700 (PDT) X-Outflank-Mailman: Message body and most headers restored to incoming version X-BeenThere: xen-devel@lists.xenproject.org List-Id: Xen developer discussion List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Errors-To: xen-devel-bounces@lists.xenproject.org Precedence: list Sender: "Xen-devel" X-Inumbo-ID: e9f42ebd-eb64-47a7-a2ce-c4d9b87a9826 From: Luca Fancellu To: xen-devel@lists.xenproject.org Cc: bertrand.marquis@arm.com, wei.chen@arm.com, Andrew Cooper , George Dunlap , Ian Jackson , Jan Beulich , Julien Grall , Stefano Stabellini , Wei Liu Subject: [PATCH v6 7/9] docs: Change Makefile and sphinx configuration for doxygen Date: Mon, 10 May 2021 09:41:03 +0100 Message-Id: <20210510084105.17108-8-luca.fancellu@arm.com> X-Mailer: git-send-email 2.17.1 In-Reply-To: <20210510084105.17108-1-luca.fancellu@arm.com> References: <20210510084105.17108-1-luca.fancellu@arm.com> Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" 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 --- .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 :=3D $(sort $(shell find misc -name '*.txt' -pr= int)) =20 PANDOCSRC-y :=3D $(sort $(shell find designs/ features/ misc/ process/ spe= cs/ \( -name '*.pandoc' -o -name '*.md' \) -print)) =20 +# Directory in which the doxygen documentation is created +# This must be kept in sync with breathe_projects value in conf.py +DOXYGEN_OUTPUT =3D doxygen-output + +# Doxygen input headers from xen-doxygen/doxy_input.list file +DOXY_LIST_SOURCES !=3D cat "xen-doxygen/doxy_input.list" +DOXY_LIST_SOURCES :=3D $(realpath $(addprefix $(XEN_ROOT)/,$(DOXY_LIST_SOU= RCES))) + +DOXY_DEPS :=3D xen.doxyfile \ + xen-doxygen/mainpage.md \ + xen-doxygen/doxygen_include.h + # Documentation targets $(foreach i,$(MAN_SECTIONS), \ $(eval DOC_MAN$(i) :=3D $(patsubst man/%.$(i),man$(i)/%.$(i), \ @@ -46,8 +58,28 @@ all: build build: html txt pdf man-pages figs =20 .PHONY: sphinx-html -sphinx-html: - sphinx-build -b html . sphinx/html +sphinx-html: $(DOXY_DEPS) $(DOXY_LIST_SOURCES) +ifneq ($(SPHINXBUILD),no) + $(DOXYGEN) xen.doxyfile + XEN_ROOT=3D$(realpath $(XEN_ROOT)) $(SPHINXBUILD) -b html . sphinx/html +else + @echo "Sphinx is not installed; skipping sphinx-html documentation." +endif + +xen.doxyfile: xen.doxyfile.in xen-doxygen/doxy_input.list + @echo "Generating $@" + @sed -e "s,@XEN_BASE@,$(realpath $(XEN_ROOT)),g" $< \ + | sed -e "s,@DOXY_OUT@,$(DOXYGEN_OUTPUT),g" > $@.tmp + @$(foreach inc,\ + $(DOXY_LIST_SOURCES),\ + echo "INPUT +=3D \"$(inc)\"" >> $@.tmp; \ + ) + mv $@.tmp $@ + +xen-doxygen/doxygen_include.h: xen-doxygen/doxygen_include.h.in + @echo "Generating $@" + @sed -e "s,@XEN_BASE@,$(realpath $(XEN_ROOT)),g" $< > $@.tmp + @mv $@.tmp $@ =20 .PHONY: html html: $(DOC_HTML) html/index.html @@ -71,7 +103,11 @@ clean: clean-man-pages $(MAKE) -C figs clean rm -rf .word_count *.aux *.dvi *.bbl *.blg *.glo *.idx *~ rm -rf *.ilg *.log *.ind *.toc *.bak *.tmp core - rm -rf html txt pdf sphinx/html + rm -rf html txt pdf sphinx $(DOXYGEN_OUTPUT) + rm -f xen.doxyfile + rm -f xen.doxyfile.tmp + rm -f xen-doxygen/doxygen_include.h + rm -f xen-doxygen/doxygen_include.h.tmp =20 .PHONY: distclean distclean: clean diff --git a/docs/conf.py b/docs/conf.py index 50e41501db..a48de42331 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -13,13 +13,17 @@ # add these directories to sys.path here. If the directory is relative to = the # documentation root, use os.path.abspath to make it absolute, like shown = here. # -# import os -# import sys +import os +import sys # sys.path.insert(0, os.path.abspath('.')) =20 =20 # -- Project information -------------------------------------------------= ---- =20 +if "XEN_ROOT" not in os.environ: + sys.exit("$XEN_ROOT environment variable undefined.") +XEN_ROOT =3D os.path.abspath(os.environ["XEN_ROOT"]) + project =3D u'Xen' copyright =3D u'2019, The Xen development community' author =3D u'The Xen development community' @@ -35,6 +39,7 @@ try: xen_subver =3D line.split(u"=3D")[1].strip() elif line.startswith(u"export XEN_EXTRAVERSION"): xen_extra =3D line.split(u"=3D")[1].split(u"$", 1)[0].strip() + except: pass finally: @@ -44,6 +49,15 @@ finally: else: version =3D release =3D u"unknown version" =20 +try: + xen_doxygen_output =3D None + + for line in open(u"Makefile"): + if line.startswith(u"DOXYGEN_OUTPUT"): + xen_doxygen_output =3D line.split(u"=3D")[1].strip() +except: + sys.exit("DOXYGEN_OUTPUT variable undefined.") + # -- General configuration -----------------------------------------------= ---- =20 # If your documentation needs a minimal Sphinx version, state it here. @@ -53,7 +67,8 @@ needs_sphinx =3D '1.4' # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions =3D [] +# breathe -> extension that integrates doxygen xml output with sphinx +extensions =3D ['breathe'] =20 # Add any paths that contain templates here, relative to this directory. templates_path =3D ['_templates'] @@ -175,6 +190,33 @@ texinfo_documents =3D [ 'Miscellaneous'), ] =20 +# -- Options for Breathe extension ---------------------------------------= ---- + +breathe_projects =3D { + "Xen": "{}/docs/{}/xml".format(XEN_ROOT, xen_doxygen_output) +} +breathe_default_project =3D "Xen" + +breathe_domain_by_extension =3D { + "h": "c", + "c": "c", +} +breathe_separate_member_pages =3D True +breathe_show_enumvalue_initializer =3D True +breathe_show_define_initializer =3D True + +# Qualifiers to a function are causing Sphihx/Breathe to warn about +# Error when parsing function declaration and more. This is a list +# of strings that the parser additionally should accept as +# attributes. +cpp_id_attributes =3D [ + '__syscall', '__deprecated', '__may_alias', + '__used', '__unused', '__weak', + '__DEPRECATED_MACRO', 'FUNC_NORETURN', + '__subsystem', +] +c_id_attributes =3D cpp_id_attributes + =20 # -- Options for Epub output ---------------------------------------------= ---- =20 --=20 2.17.1