mirror of
https://github.com/projectacrn/acrn-hypervisor.git
synced 2025-05-30 02:45:20 +00:00
487961ace6
We use a post-processor to scan the output log from Sphinx to remove known errors and warnings before deciding if the Sphinx build was successful. If an exception happened during the Sphinx build, (see about the error would appear. Update the Makefile to not stop on errors for the Sphinx build. The post-processor will stop the make by returning an error code if it finds unexpected errors in the log. Tracked-On: #7249 Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
107 lines
4.2 KiB
Makefile
107 lines
4.2 KiB
Makefile
# Minimal makefile for Sphinx documentation
|
|
#
|
|
|
|
ifeq ($(VERBOSE),1)
|
|
Q =
|
|
else
|
|
Q = @
|
|
endif
|
|
|
|
# You can set these variables from the command line.
|
|
SPHINXOPTS ?= -q
|
|
SPHINXBUILD = sphinx-build
|
|
SPHINXPROJ = "Project ACRN"
|
|
BUILDDIR ?= _build
|
|
SOURCEDIR = $(BUILDDIR)/rst
|
|
LATEXMKOPTS = -silent
|
|
|
|
# document publication assumes the folder structure is setup
|
|
# with the acrn-hypervisor and projectacrn.github.io repos as
|
|
# sibling folders and make is run inside the acrn-hypervisor/docs
|
|
# folder.
|
|
|
|
ACRN_BASE = "$(CURDIR)/../.."
|
|
DOC_TAG ?= development
|
|
RELEASE ?= latest
|
|
PUBLISHDIR = $(ACRN_BASE)/projectacrn.github.io/$(RELEASE)
|
|
|
|
# Put it first so that "make" without argument is like "make help".
|
|
help:
|
|
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(OPTS)
|
|
@echo ""
|
|
@echo "make publish"
|
|
@echo " publish generated html to projectacrn.github.io site:"
|
|
@echo " specify RELEASE=name to publish as a tagged release version"
|
|
@echo " and placed in a version subfolder. Requires repo merge permission."
|
|
|
|
.PHONY: help Makefile copy-to-sourcedir doxy content html singlehtml clean publish
|
|
|
|
# Generate the doxygen xml (for Sphinx) and copy the doxygen html to the
|
|
# api folder for publishing along with the Sphinx-generated API docs.
|
|
# This is where we tweak the "pre" API comments into "preconditions"
|
|
# Note that this step starts with an empty doc.log while the others append
|
|
doxy:
|
|
$(Q)(cat acrn.doxyfile ; echo "OUTPUT_DIRECTORY=$(SOURCEDIR)/doxygen" ) | doxygen - > $(BUILDDIR)/doc.log 2>&1
|
|
$(Q)find $(SOURCEDIR)/doxygen/xml/* | xargs sed -i 's/simplesect kind="pre"/simplesect kind="preconditions"/'
|
|
|
|
# Copy all the rst content (and images, etc) into the _build/rst folder
|
|
# including rst content and xsd files from the /misc folder that we'll
|
|
# use to generate config option documentation
|
|
|
|
content:
|
|
$(Q)mkdir -p $(SOURCEDIR)
|
|
$(Q)rsync -rt --exclude=$(BUILDDIR) . $(SOURCEDIR)
|
|
$(Q)scripts/extract_content.py $(SOURCEDIR) misc
|
|
$(Q)mkdir -p $(SOURCEDIR)/misc/config_tools/schema
|
|
$(Q)rsync -rt ../misc/config_tools/schema/*.xsd $(SOURCEDIR)/misc/config_tools/schema
|
|
$(Q)xsltproc -xinclude ./scripts/configdoc.xsl $(SOURCEDIR)/misc/config_tools/schema/config.xsd > $(SOURCEDIR)/reference/configdoc.txt
|
|
|
|
|
|
html: content doxy
|
|
@echo making HTML content
|
|
$(Q)./scripts/show-versions.py
|
|
-$(Q)$(SPHINXBUILD) -t $(DOC_TAG) -b html -d $(BUILDDIR)/doctrees $(SOURCEDIR) $(BUILDDIR)/html $(SPHINXOPTS) $(OPTS) >> $(BUILDDIR)/doc.log 2>&1
|
|
$(Q)./scripts/filter-doc-log.sh $(BUILDDIR)/doc.log
|
|
|
|
singlehtml: content doxy
|
|
-$(Q)$(SPHINXBUILD) -t $(DOC_TAG) -b singlehtml -d $(BUILDDIR)/doctrees $(SOURCEDIR) $(BUILDDIR)/html $(SPHINXOPTS) $(OPTS) >> $(BUILDDIR)/doc.log 2>&1
|
|
$(Q)./scripts/filter-doc-log.sh $(BUILDDIR)/doc.log
|
|
|
|
pdf: html
|
|
@echo now making $(BUILDDIR)/latex/acrn.pdf
|
|
-$(Q)make -silent latexpdf LATEXMKOPTS=$(LATEXMKOPTS) >> $(BUILDDIR)/doc.log 2>&1
|
|
$(Q)./scripts/filter-doc-log.sh $(BUILDDIR)/doc.log
|
|
|
|
|
|
# Remove generated content (Sphinx and doxygen)
|
|
|
|
clean:
|
|
rm -fr $(BUILDDIR)
|
|
|
|
|
|
# Copy material over to the GitHub pages staging repo
|
|
# along with a README, index.html redirect to latest/index.html, robots.txt (for
|
|
# search exclusions), and tweak the Sphinx-generated 404.html to work as the
|
|
# site-wide 404 response page. (We generate the 404.html with Sphinx so it has
|
|
# the current left navigation contents and overall style.)
|
|
|
|
publish:
|
|
mkdir -p $(PUBLISHDIR)
|
|
cd $(PUBLISHDIR)/..; git pull origin master
|
|
rm -fr $(PUBLISHDIR)/*
|
|
cp -r $(BUILDDIR)/html/* $(PUBLISHDIR)
|
|
ifeq ($(RELEASE),latest)
|
|
cp scripts/publish-README.md $(PUBLISHDIR)/../README.md
|
|
scripts/publish-redirect.sh $(PUBLISHDIR)/../index.html latest/index.html
|
|
scripts/publish-redirect.sh $(PUBLISHDIR)/../hardware.html latest/reference/hardware.html
|
|
cp scripts/publish-robots.txt $(PUBLISHDIR)/../robots.txt
|
|
sed 's/<head>/<head>\n <base href="https:\/\/projectacrn.github.io\/latest\/">/' $(BUILDDIR)/html/404.html > $(PUBLISHDIR)/../404.html
|
|
endif
|
|
cd $(PUBLISHDIR)/..; git add -A; git commit -s -m "publish $(RELEASE)"; git push origin master;
|
|
|
|
|
|
# Catch-all target: route all unknown targets to Sphinx using the new
|
|
# "make mode" option. $(OPTS) is meant as a shortcut for $(SPHINXOPTS).
|
|
%: Makefile
|
|
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(OPTS)
|