@@ -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
@@ -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
@@ -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 -------------------------------------------------
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> --- 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(-)