mirror of
https://github.com/projectacrn/acrn-hypervisor.git
synced 2025-06-20 12:42:54 +00:00
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 <david.b.kinder@intel.com>
This commit is contained in:
David B. Kinder
Jack Ren
parent
6b1782b360
commit
b997e590f2
15
doc/Makefile
15
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
|
||||
|
||||
22
doc/_templates/breadcrumbs.html
vendored
Normal file
22
doc/_templates/breadcrumbs.html
vendored
Normal file
@ -0,0 +1,22 @@
|
||||
{% extends "!breadcrumbs.html" %}
|
||||
{% block breadcrumbs_aside %}
|
||||
|
||||
<li class="wy-breadcrumbs-aside">
|
||||
<div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
|
||||
<span class="rst-current-version" data-toggle="rst-current-version">
|
||||
<span class="fa fa-book"> Project ACRN</span>
|
||||
version: {{ current_version }}
|
||||
<span class="fa fa-caret-down"></span>
|
||||
</span>
|
||||
<div class="rst-other-versions">
|
||||
<dl>
|
||||
<dt>Versions</dt>
|
||||
{% for slug, url in versions %}
|
||||
<dd><a href="{{ url }}">{{ slug }}</a></dd>
|
||||
{% endfor %}
|
||||
</dl>
|
||||
</div>
|
||||
</div>
|
||||
</li>
|
||||
{# {{ super() }} #}
|
||||
{% endblock %}
|
||||
26
doc/conf.py
26
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 /<relnum>
|
||||
# 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')
|
||||
|
||||
10
doc/scripts/publish-index.html
Normal file
10
doc/scripts/publish-index.html
Normal file
@ -0,0 +1,10 @@
|
||||
<html>
|
||||
<head>
|
||||
<title>ACRN Hypervisor documentation</title>
|
||||
<meta http-equiv="refresh" content="0; URL=latest/index.html">
|
||||
<meta name="keywords" content="automatic redirection">
|
||||
</head>
|
||||
<body>
|
||||
Please visit the <a href="/latest/">latest ARCN documentation</a>
|
||||
</body>
|
||||
</html>
|
||||
23
doc/static/acrn-custom.css
vendored
23
doc/static/acrn-custom.css
vendored
@ -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);
|
||||
|
||||
Loading…
Reference in New Issue
Block a user