[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [PATCH v7 7/9] docs: Change Makefile and sphinx configuration for doxygen
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> --- 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 ------------------------------------------------- -- 2.17.1
|
Lists.xenproject.org is hosted with RackSpace, monitoring our |