From b997e590f29bf2c714ae10b07274c7b5948b582e Mon Sep 17 00:00:00 2001 From: "David B. Kinder" Date: Fri, 13 Apr 2018 14:36:25 -0700 Subject: [PATCH] doc: add support for publishing versioned docs add navigation to (manually) maintained list (in conf.py) of versioned docs, and update generating and publishing processes to be version-aware. Adds a file to redirect root references to /latest folder now (since we can't update the server redirects). Might break some links to pages within the site from external sites. Signed-off-by: David B. Kinder --- doc/Makefile | 15 +++++++++------ doc/_templates/breadcrumbs.html | 22 ++++++++++++++++++++++ doc/conf.py | 26 ++++++++++++++++++++++++-- doc/scripts/publish-index.html | 10 ++++++++++ doc/static/acrn-custom.css | 23 ++++++++++++++++++++++- 5 files changed, 87 insertions(+), 9 deletions(-) create mode 100644 doc/_templates/breadcrumbs.html create mode 100644 doc/scripts/publish-index.html diff --git a/doc/Makefile b/doc/Makefile index 4859f8608..2c5109585 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -8,13 +8,15 @@ else endif # You can set these variables from the command line. -SPHINXOPTS = -q +SPHINXOPTS ?= -q SPHINXBUILD = sphinx-build SPHINXPROJ = "Project ACRN" SOURCEDIR = . BUILDDIR = _build -PUBLISHDIR = ../projectacrn.github.io +DOC_TAG ?= development +RELEASE ?= latest +PUBLISHDIR = ../projectacrn.github.io/$(RELEASE) # Put it first so that "make" without argument is like "make help". help: @@ -30,10 +32,10 @@ pullsource: # api folder for publishing along with the Sphinx-generated API docs. doxy: pullsource - $(Q)(cat acrn.doxyfile) | doxygen - 2>&1 + $(Q)(cat acrn.doxyfile) | doxygen - > doc.log 2>&1 html: doxy - -$(Q)$(SPHINXBUILD) -b html -d $(BUILDDIR)/doctrees $(SOURCEDIR) $(BUILDDIR)/html $(SPHINXOPTS) $(O) > doc.log 2>&1 + -$(Q)$(SPHINXBUILD) -t $(DOC_TAG) -b html -d $(BUILDDIR)/doctrees $(SOURCEDIR) $(BUILDDIR)/html $(SPHINXOPTS) $(O) >> doc.log 2>&1 $(Q)./scripts/filter-doc-log.sh doc.log @@ -48,8 +50,9 @@ clean: publish: rm -fr $(PUBLISHDIR)/* cp -r $(BUILDDIR)/html/* $(PUBLISHDIR) - cp scripts/publish-README.md $(PUBLISHDIR)/README.md - cd $(PUBLISHDIR); git add -A; git commit -s -m "publish"; git push origin master; + cp scripts/publish-README.md $(PUBLISHDIR)/../README.md + cp scripts/publish-index.html $(PUBLISHDIR)/../index.html + 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 diff --git a/doc/_templates/breadcrumbs.html b/doc/_templates/breadcrumbs.html new file mode 100644 index 000000000..f23658606 --- /dev/null +++ b/doc/_templates/breadcrumbs.html @@ -0,0 +1,22 @@ +{% extends "!breadcrumbs.html" %} +{% block breadcrumbs_aside %} + +
  • +
    + + Project ACRN + version: {{ current_version }} + + +
    +
    +
    Versions
    + {% for slug, url in versions %} +
    {{ slug }}
    + {% endfor %} +
    +
    +
    +
    • +{# {{ super() }} #} +{% endblock %} diff --git a/doc/conf.py b/doc/conf.py index ae0ab7481..f6c1ab5ec 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -87,6 +87,9 @@ finally: else: sys.stderr.write('Warning: Could not extract hypervisor version from Makefile\n') version = release = "unknown" + + + # # The short X.Y version. # version = u'0.1' @@ -141,8 +144,26 @@ else: # Toc options 'collapse_navigation': False, 'sticky_navigation': True, - 'navigation_depth': 4 -} + 'navigation_depth': 4, + } + + +# Here's where we (manually) list the document versions maintained on +# the published doc website. On a daily basis we publish to the +# /latest folder but when releases are made, we publish to a / +# folder (specified via RELEASE=name on the make command). + +if tags.has('release'): + current_version = version +else: + version = current_version = "latest" + +html_context = { + 'current_version': current_version, + 'versions': ( ("latest", "/latest/"), + ("0.1-rc4", "/0.1-rc4/"), + ) + } # Theme options are theme-specific and customize the look and feel of a theme @@ -258,3 +279,4 @@ breathe_projects = { "Project ACRN" : "doxygen/xml", } breathe_default_project = "Project ACRN" +breathe_default_members = ('members', 'undoc-members', 'content-only') diff --git a/doc/scripts/publish-index.html b/doc/scripts/publish-index.html new file mode 100644 index 000000000..5fe9d1579 --- /dev/null +++ b/doc/scripts/publish-index.html @@ -0,0 +1,10 @@ + + +ACRN Hypervisor documentation + + + + +Please visit the latest ARCN documentation + + diff --git a/doc/static/acrn-custom.css b/doc/static/acrn-custom.css index 244f85a31..a6e964765 100644 --- a/doc/static/acrn-custom.css +++ b/doc/static/acrn-custom.css @@ -1,4 +1,4 @@ -/* -- Extra CSS styles for CWP content (RTD theme) ----------------------- */ +/* -- Extra CSS styles for ACRN content (RTD theme) ----------------------- */ /* make the page width fill the window */ .wy-nav-content { @@ -14,6 +14,27 @@ } */ +/* tweak doc version selection */ +.rst-versions { + position: static; + border-top: none; + padding: 0px; +} + +.rst-versions .rst-current-version { + padding: 5px; + background-color: #2980B9; + color: #80FF80; +} + +.rst-versions .rst-other-versions { + padding: 5px; +} + +div.rst-other-versions dl { + margin-bottom: 0; +} + /* Make the version number more visible */ .wy-side-nav-search>div.version { color: rgba(255,255,255,1);