From patchwork Mon Jul 5 10:51:01 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Luca Fancellu X-Patchwork-Id: 12358851 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-16.8 required=3.0 tests=BAYES_00, HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER,INCLUDES_PATCH, MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS,USER_AGENT_GIT autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 5ECE4C07E9C for ; Mon, 5 Jul 2021 10:55:57 +0000 (UTC) Received: from lists.xenproject.org (lists.xenproject.org [192.237.175.120]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id 2AA766135B for ; Mon, 5 Jul 2021 10:55:57 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 2AA766135B Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=arm.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=xen-devel-bounces@lists.xenproject.org Received: from list by lists.xenproject.org with outflank-mailman.150108.277675 (Exim 4.92) (envelope-from ) id 1m0MGU-0007hf-Kc; Mon, 05 Jul 2021 10:55:50 +0000 X-Outflank-Mailman: Message body and most headers restored to incoming version Received: by outflank-mailman (output) from mailman id 150108.277675; Mon, 05 Jul 2021 10:55:50 +0000 Received: from localhost ([127.0.0.1] helo=lists.xenproject.org) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1m0MGU-0007gi-G4; Mon, 05 Jul 2021 10:55:50 +0000 Received: by outflank-mailman (input) for mailman id 150108; Mon, 05 Jul 2021 10:55:49 +0000 Received: from us1-rack-iad1.inumbo.com ([172.99.69.81]) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1m0MGT-0003rB-DB for xen-devel@lists.xenproject.org; Mon, 05 Jul 2021 10:55:49 +0000 Received: from foss.arm.com (unknown [217.140.110.172]) by us1-rack-iad1.inumbo.com (Halon) with ESMTP id 3c1f91db-b0f4-4e2b-8467-03772ff4fa00; Mon, 05 Jul 2021 10:55:29 +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 C65C71063; Mon, 5 Jul 2021 03:55:28 -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 E66E83F5A1; Mon, 5 Jul 2021 03:55:26 -0700 (PDT) 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: 3c1f91db-b0f4-4e2b-8467-03772ff4fa00 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 v7 7/9] docs: Change Makefile and sphinx configuration for doxygen Date: Mon, 5 Jul 2021 11:51:01 +0100 Message-Id: <20210705105103.14509-8-luca.fancellu@arm.com> X-Mailer: git-send-email 2.17.1 In-Reply-To: <20210705105103.14509-1-luca.fancellu@arm.com> References: <20210705105103.14509-1-luca.fancellu@arm.com> 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 --- v7 changes: - in conf.py, get DOXYGEN_OUTPUT as environmental variable and add new types into cpp_id_attributes --- .gitignore | 6 ++++++ docs/Makefile | 43 ++++++++++++++++++++++++++++++++++++++++--- docs/conf.py | 43 ++++++++++++++++++++++++++++++++++++++++--- 3 files changed, 86 insertions(+), 6 deletions(-) diff --git a/.gitignore b/.gitignore index 38a085e398..ef0b0ed101 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..c0699a2f1b 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))) + +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,29 @@ 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) + $(DOXYGEN) xen.doxyfile + XEN_ROOT=$(realpath $(XEN_ROOT)) DOXYGEN_OUTPUT=$(DOXYGEN_OUTPUT) \ + $(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 += \"$(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 $@ .PHONY: html html: $(DOC_HTML) html/index.html @@ -71,7 +104,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 .PHONY: distclean distclean: clean diff --git a/docs/conf.py b/docs/conf.py index 50e41501db..d5cd305f19 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('.')) # -- Project information ----------------------------------------------------- +if "XEN_ROOT" not in os.environ: + sys.exit("$XEN_ROOT environment variable undefined.") +XEN_ROOT = os.path.abspath(os.environ["XEN_ROOT"]) + project = u'Xen' copyright = u'2019, The Xen development community' author = u'The Xen development community' @@ -44,6 +48,10 @@ finally: else: version = release = u"unknown version" +if "DOXYGEN_OUTPUT" not in os.environ: + sys.exit("$DOXYGEN_OUTPUT environment variable undefined.") +xen_doxygen_output = os.environ["DOXYGEN_OUTPUT"] + # -- General configuration --------------------------------------------------- # If your documentation needs a minimal Sphinx version, state it here. @@ -53,7 +61,8 @@ needs_sphinx = '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 = [] +# breathe -> extension that integrates doxygen xml output with sphinx +extensions = ['breathe'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -175,6 +184,34 @@ texinfo_documents = [ 'Miscellaneous'), ] +# -- Options for Breathe extension ------------------------------------------- + +breathe_projects = { + "Xen": "{}/docs/{}/xml".format(XEN_ROOT, xen_doxygen_output) +} +breathe_default_project = "Xen" + +breathe_domain_by_extension = { + "h": "c", + "c": "c", +} +breathe_separate_member_pages = True +breathe_show_enumvalue_initializer = True +breathe_show_define_initializer = 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 = [ + '__syscall', '__deprecated', '__may_alias', + '__used', '__unused', '__weak', + '__DEPRECATED_MACRO', 'FUNC_NORETURN', + '__subsystem', '__packed', '__init', + '__attribute__', '__aligned__' +] +c_id_attributes = cpp_id_attributes + # -- Options for Epub output -------------------------------------------------