1# Minimal makefile for Sphinx documentation
2#
3
4ifeq ($(VERBOSE),1)
5  Q =
6else
7  Q = @
8endif
9
10# You can set these variables from the command line.
11SPHINXOPTS    ?= -q
12SPHINXBUILD   = sphinx-build
13SPHINXPROJ    = "Project ACRN"
14BUILDDIR      ?= _build
15SOURCEDIR     = $(BUILDDIR)/rst
16LATEXMKOPTS   = "-silent -f"
17
18# should the config option doc show hidden config options?
19XSLTPARAM     ?= --stringparam showHidden 'n'
20
21# document publication assumes the folder structure is setup
22# with the acrn-hypervisor and projectacrn.github.io repos as
23# sibling folders and make is run inside the acrn-hypervisor/docs
24# folder.
25
26ACRN_BASE     = "$(CURDIR)/../.."
27DOC_TAG      ?= development
28RELEASE      ?= latest
29PUBLISHDIR    = $(ACRN_BASE)/projectacrn.github.io/$(RELEASE)
30
31# Put it first so that "make" without argument is like "make help".
32help:
33	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(OPTS)
34	@echo ""
35	@echo "make publish"
36	@echo "   publish generated html to projectacrn.github.io site:"
37	@echo "   specify RELEASE=name to publish as a tagged release version"
38	@echo "   and placed in a version subfolder.  Requires repo merge permission."
39
40.PHONY: help Makefile copy-to-sourcedir doxy content html singlehtml clean publish
41
42# Generate the doxygen xml (for Sphinx) and copy the doxygen html to the
43# api folder for publishing along with the Sphinx-generated API docs.
44# This is where we tweak the "pre" API comments into "preconditions"
45# Note that this step starts with an empty doc.log while the others append
46doxy:
47	$(Q)(cat acrn.doxyfile ; echo "OUTPUT_DIRECTORY=$(SOURCEDIR)/doxygen" ) | doxygen - > $(BUILDDIR)/doc.log 2>&1
48	$(Q)find $(SOURCEDIR)/doxygen/xml/* | xargs sed -i 's/simplesect kind="pre"/simplesect kind="preconditions"/'
49
50# Copy all the rst content (and images, etc) into the _build/rst folder
51# including rst content and xsd files from the /misc folder that we'll
52# use to generate config option documentation
53
54content:
55	$(Q)mkdir -p $(SOURCEDIR)
56	$(Q)rsync -rt --exclude=$(BUILDDIR) . $(SOURCEDIR)
57	$(Q)scripts/extract_content.py $(SOURCEDIR) misc
58	$(Q)mkdir -p $(SOURCEDIR)/misc/config_tools/schema
59	$(Q)rsync -rt ../misc/config_tools/schema/*.xsd $(SOURCEDIR)/misc/config_tools/schema
60	$(Q)xsltproc $(XSLTPARAM) -xinclude ./scripts/configdoc.xsl $(SOURCEDIR)/misc/config_tools/schema/config.xsd > $(SOURCEDIR)/reference/configdoc.txt
61
62
63html: content doxy
64	@echo making HTML content
65	$(Q)./scripts/show-versions.py
66	-$(Q)$(SPHINXBUILD) -t $(DOC_TAG) -b html -d $(BUILDDIR)/doctrees $(SOURCEDIR) $(BUILDDIR)/html $(SPHINXOPTS) $(OPTS) >> $(BUILDDIR)/doc.log 2>&1
67	$(Q)./scripts/filter-doc-log.sh $(BUILDDIR)/doc.log
68
69singlehtml: content doxy
70	-$(Q)$(SPHINXBUILD) -t $(DOC_TAG) -b singlehtml -d $(BUILDDIR)/doctrees $(SOURCEDIR) $(BUILDDIR)/html $(SPHINXOPTS) $(OPTS) >> $(BUILDDIR)/doc.log 2>&1
71	$(Q)./scripts/filter-doc-log.sh $(BUILDDIR)/doc.log
72
73pdf: html
74	@echo now making $(BUILDDIR)/latex/acrn.pdf
75	$(Q)make -silent latexpdf LATEXMKOPTS=$(LATEXMKOPTS) >> $(BUILDDIR)/doc.log 2>&1
76	$(Q)./scripts/filter-doc-log.sh $(BUILDDIR)/doc.log
77
78
79# Remove generated content (Sphinx and doxygen)
80
81clean:
82	rm -fr $(BUILDDIR)
83
84
85# Copy material over to the GitHub pages staging repo
86# along with a README, index.html redirect to latest/index.html, robots.txt (for
87# search exclusions), and tweak the Sphinx-generated 404.html to work as the
88# site-wide 404 response page.  (We generate the 404.html with Sphinx so it has
89# the current left navigation contents and overall style.)
90
91publish:
92	mkdir -p $(PUBLISHDIR)
93	cd $(PUBLISHDIR)/..; git pull origin master
94	rm -fr $(PUBLISHDIR)/*
95	cp -r $(BUILDDIR)/html/* $(PUBLISHDIR)
96ifeq ($(RELEASE),latest)
97	cp scripts/publish-README.md $(PUBLISHDIR)/../README.md
98	scripts/publish-redirect.sh $(PUBLISHDIR)/../index.html latest/index.html
99	scripts/publish-redirect.sh $(PUBLISHDIR)/../hardware.html latest/reference/hardware.html
100	cp scripts/publish-robots.txt $(PUBLISHDIR)/../robots.txt
101	sed 's/<head>/<head>\n  <base href="https:\/\/projectacrn.github.io\/latest\/">/' $(BUILDDIR)/html/404.html > $(PUBLISHDIR)/../404.html
102endif
103	cd $(PUBLISHDIR)/..; git add -A; git commit -s -m "publish $(RELEASE)"; git push origin master;
104
105
106# Catch-all target: route all unknown targets to Sphinx using the new
107# "make mode" option.  $(OPTS) is meant as a shortcut for $(SPHINXOPTS).
108%: Makefile
109	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(OPTS)
110