Skip to content

Commit c59792e

Browse files
oliver-sandersoliver-sanders
committed
Add versioning to rose make-docs
* Changed docs structure to $ROSE_HOME/doc/$VERSION/$FORMAT * Added support for Jekyll into the repository * HTML static redirects now generated on build * New version selector for html documentation (ws only)
1 parent a25654b commit c59792e

File tree

10 files changed

+259
-78
lines changed

10 files changed

+259
-78
lines changed

‎404.md

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
[comment]: <> (This is the 404 page as used on the Github Pages site.)
2+
3+
## The Rose Documentation Has Moved
4+
5+
Please update your bookmarks to: http://metomi.github.io/rose

‎_config.yml

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# This file configures the Jekyll static web builder (https://jekyllrb.com/) as
2+
# used by Github Pages.
3+
4+
# Jekyll treats directories beginning with underscores as having special meaning
5+
# and omits them from the build. This can be overridden by manually including
6+
# directories using "include".
7+
# https://help.github.com/articles/files-that-start-with-an-underscore-are-missing/
8+
# NOTE: Only the directory name should be specified not the full path.
9+
include: [
10+
"_downloads",
11+
"_images",
12+
"_modules",
13+
"_sources",
14+
"_static"
15+
]

‎bin/rose-make-docs

+125-35
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,9 @@
3737
# errors.
3838
# --debug
3939
# Run `make` with the --debug option.
40+
# --default-version=VERSION
41+
# By default the current version is symlinked as the default version,
42+
# provide an alternative version to override this.
4043
#
4144
# BUILD
4245
# The format(s) to build the documentation in - default html.
@@ -51,8 +54,8 @@
5154
# `latexpdf`
5255
# For building PDF documentation.
5356
# `clean`
54-
# Removes all builds (rose make-docs clean <build> will force a
55-
# complete re-build).
57+
# Removes all built documentation for the current rose version.
58+
# (use `rm -rf doc` to remove all documentation).
5659
#
5760
# DEVELOPMENT BUILDS
5861
# For development purposes use the following BUILDs:
@@ -65,38 +68,29 @@
6568
#-----------------------------------------------------------------------------
6669
set -e
6770
set -o pipefail
71+
shopt -s extglob
6872

6973
# Move into rose directory
70-
cd "$(dirname $0)/../"
74+
cd "$(dirname "$0")/../"
7175

72-
VENV_PATH='venv' # Path for virtualenv.
73-
USING_VENV=false # Set to `true` when the virtualenv is being used.
74-
SPHINX_PATH=sphinx # Path to the sphinx directory.
75-
76-
venv-activate () {
77-
USING_VENV=true
78-
. "${VENV_PATH}/bin/activate"
79-
}
80-
81-
venv-install () {
82-
venv-destroy
83-
virtualenv --python=python2.7 "${VENV_PATH}"
84-
venv-activate
85-
pip install sphinx
86-
pip install sphinx_rtd_theme
87-
pip install sphinxcontrib-httpdomain
88-
pip install hieroglyph
89-
}
90-
91-
venv-deactivate () {
92-
deactivate >/dev/null 2>&1 || true
93-
}
94-
95-
venv-destroy () {
96-
venv-deactivate
97-
rm -rf "${VENV_PATH}"
98-
}
76+
# Path for virtualenv.
77+
VENV_PATH='venv'
78+
# Set to `true` when the virtualenv is being used.
79+
USING_VENV=false
80+
# Path to the sphinx directory.
81+
SPHINX_PATH=sphinx
82+
# pick up official rose version
83+
. "${ROSE_HOME}/rose-version"
84+
# documentation root output directory
85+
DOCS_DIR="${ROSE_HOME}/doc"
86+
# documentation output directory for this version
87+
BUILD_DIR="${DOCS_DIR}/${ROSE_VERSION}"
88+
# glob for documented rose versions
89+
DOC_VERSIONS=!(*.html|.git|doc|versions.json|"${DEFAULT_ALIAS}")
90+
# glob for documentation formats within a rose version
91+
DOC_FORMATS=!(*.html|doctrees)
9992

93+
# is the virtualenv command available
10094
if which virtualenv >/dev/null 2>&1; then
10195
VENV_COMPLIANT=true
10296
else
@@ -109,7 +103,9 @@ FORCE=false
109103
DEV_MODE=false
110104
DEBUG=''
111105
BUILDS=''
112-
SPHINXOPTS=''
106+
SPHINX_OPTS=''
107+
DEFAULT_ALIAS='doc'
108+
DEFAULT_VERSION=
113109
while [[ $# -gt 0 ]]; do
114110
case $1 in
115111
--venv)
@@ -125,13 +121,18 @@ while [[ $# -gt 0 ]]; do
125121
shift
126122
;;
127123
--strict)
128-
SPHINXOPTS='SPHINXOPTS=-aEW'
124+
SPHINX_OPTS='SPHINX_OPTS=-aEW'
129125
shift
130126
;;
131127
--debug)
132128
DEBUG='--debug'
133129
shift
134130
;;
131+
--default-version)
132+
DEFAULT_VERSION="$2"
133+
shift
134+
shift
135+
;;
135136
*)
136137
BUILDS="${BUILDS} $1"
137138
shift
@@ -142,6 +143,79 @@ if [[ -z "${BUILDS}" ]]; then
142143
BUILDS='html'
143144
fi
144145

146+
147+
venv-activate () {
148+
USING_VENV=true
149+
. "${VENV_PATH}/bin/activate"
150+
}
151+
152+
venv-install () {
153+
venv-destroy
154+
virtualenv --python=python2.7 "${VENV_PATH}"
155+
venv-activate
156+
pip install sphinx
157+
pip install sphinx_rtd_theme
158+
pip install sphinxcontrib-httpdomain
159+
pip install hieroglyph
160+
}
161+
162+
venv-deactivate () {
163+
deactivate >/dev/null 2>&1 || true
164+
}
165+
166+
venv-destroy () {
167+
venv-deactivate
168+
rm -rf "${VENV_PATH}"
169+
}
170+
171+
json_list () {
172+
# write out a bash array as a JSON list
173+
echo -n "[\"$(local IFS=','; echo "$*" | sed 's/,/", "/g';)\"]"
174+
}
175+
176+
version_file () {
177+
# output the dictionary {"version": ["build", ...]} in JSON format
178+
DOCS_DIR="$1"
179+
DEFAULT_ALIAS="$2"
180+
181+
echo '{'
182+
# scrape filesystem for list of rose versions which have built docs
183+
VERSIONS=( $(cd "${DOCS_DIR}"; echo $DOC_VERSIONS) )
184+
for version in "${VERSIONS[@]}"; do
185+
# scrape filesystem to get list of formats this version is available in
186+
formats=( $(cd "${DOCS_DIR}/${version}"; echo $DOC_FORMATS) )
187+
list=" \"${version}\": $(json_list ${formats})"
188+
if [[ $version == "${VERSIONS[$(( ${#VERSIONS[@]} - 1 ))]}" ]]; then
189+
# JSON doesn't permit a comma after the last item in a collection
190+
echo "${list}"
191+
else
192+
echo "${list},"
193+
fi
194+
done
195+
echo '}'
196+
}
197+
198+
html_redirect () {
199+
# write an html file to $2 which auto-redirects to the relative path $1
200+
SRC="$1"
201+
DEST="$2"
202+
203+
cat >"$2" << __HTML__
204+
<!DOCTYPE html>
205+
<html>
206+
<head>
207+
<title>Rose Documentation</title>
208+
<meta http-equiv="REFRESH" content="0;url=$1">
209+
</head>
210+
<body>
211+
<p>If not automatically redirected, please click
212+
<a href="$1">Rose Documentation</a>.</p>
213+
</body>
214+
</html>
215+
__HTML__
216+
}
217+
218+
145219
# Use virtualenv if present and requested or if we are in development mode.
146220
if "${DEV_MODE}" || "${VENV_MODE}"; then
147221
if ! "${VENV_COMPLIANT}"; then
@@ -174,7 +248,7 @@ if ! rose-check-software --doc >/dev/null; then
174248

175249
echo
176250
echo 'The documentation can still be built by installing dependencies'
177-
echo 'in a python virtual enironment (virtualenv). This environment'
251+
echo 'in a python virtual environment (virtualenv). This environment'
178252
echo "will be created in rose/${VENV_PATH} and will be removed after"
179253
echo 'use. To keep the virtualenv for future builds run this command'
180254
echo 'with the "--dev" option.'
@@ -198,9 +272,25 @@ if ! rose-check-software --doc >/dev/null; then
198272
fi
199273
fi
200274

201-
# Run sphinx make.
202-
if make ${DEBUG} -C "${SPHINX_PATH}" ${BUILDS} ${SPHINXOPTS}; then
275+
# makefile argument to set the output directory for this build
276+
SPHINX_OPTS="${SPHINX_OPTS} BUILDDIR=${DOCS_DIR}/${ROSE_VERSION}"
277+
278+
# run sphinx-build
279+
if make ${DEBUG} -C "${SPHINX_PATH}" ${BUILDS} ${SPHINX_OPTS}; then
203280
RET=0
281+
# output file containing details of all versions and formats the
282+
# documentation has been built in (locally) for the version / format
283+
# switching pane
284+
version_file "${DOCS_DIR}" "${DEFAULT_ALIAS}" > "${DOCS_DIR}/versions.json"
285+
# symlink this version as the default
286+
(
287+
cd "${DOCS_DIR}"
288+
rm "${DEFAULT_ALIAS}" 2>/dev/null || true
289+
ln -s "${DEFAULT_VERSION:-$ROSE_VERSION}" "${DEFAULT_ALIAS}"
290+
)
291+
# symlink landing pages
292+
html_redirect "${DEFAULT_ALIAS}/html/index.html" 'doc/index.html'
293+
html_redirect "html/index.html" "doc/${ROSE_VERSION}/index.html"
204294
else
205295
RET=1
206296
fi

‎index.html

-13
This file was deleted.

‎index.html

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
doc/current/html/index.html

‎lib/python/rose/resource.py

+11-4
Original file line numberDiff line numberDiff line change
@@ -147,10 +147,17 @@ def get_util_name(self, separator=" "):
147147
except KeyError:
148148
return os.path.basename(sys.argv[0])
149149

150-
def get_version(self):
151-
"""Return ROSE_VERSION."""
152-
version = os.getenv("ROSE_VERSION")
153-
if version is None:
150+
def get_version(self, ignore_environment=False):
151+
"""Return ROSE_VERSION.
152+
153+
Args:
154+
ignore_environment (bool): Ignore the value of the ROSE_VERSION
155+
environment variable if present.
156+
"""
157+
version = None
158+
if not ignore_environment:
159+
version = os.getenv("ROSE_VERSION")
160+
if not version:
154161
for line in open(self.get_util_home("rose-version")):
155162
if line.startswith("ROSE_VERSION="):
156163
value = line.replace("ROSE_VERSION=", "")

‎rose.html

-13
This file was deleted.

‎rose.html

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
doc/current/html/index.html

‎sphinx/_static/js/versioning.js

+40
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
$(document).ready(function() {
2+
$.ajax({
3+
'async': false,
4+
'type': 'GET',
5+
'url': root_dir + 'versions.json',
6+
dataType: 'json',
7+
success: function (versions) {
8+
// the DOM element to append version and format selectors to
9+
var ele = $('#version-selector');
10+
11+
// construct version selector
12+
var ver = ele.append($('<dl />'));
13+
$(ver).append($('<dt />').append('Versions'));
14+
for (let version of Object.keys(versions).sort().reverse()) {
15+
$(ver).append($('<dd />')
16+
.append($('<a />')
17+
.attr({'href': root_dir + version + '/' +
18+
current_builder + '/' +
19+
current_page_name})
20+
.append(version)
21+
)
22+
);
23+
}
24+
25+
// construct format selector
26+
var bui = ele.append($('<dl />'));
27+
$(bui).append($('<dt />').append('Formats'));
28+
for (let builder_for_version of versions[current_version].sort()) {
29+
$(bui).append($('<dd />')
30+
.append($('<a />')
31+
.attr({'href': root_dir + current_version + '/' +
32+
builder_for_version + '/' +
33+
current_page_name})
34+
.append(builder_for_version)
35+
)
36+
);
37+
}
38+
}
39+
});
40+
});

‎sphinx/_templates/layout.html

+8-2
Original file line numberDiff line numberDiff line change
@@ -2,5 +2,11 @@
22

33
{% extends "!layout.html" %}
44

5-
{% set css_files = css_files + ['_static/css/rtd-theme-fix.css', '_static/pygments.css'] %}
6-
{% set script_files = script_files + ['_static/js/rtd-theme-extensions.js'] %}
5+
{% set css_files = css_files + [
6+
'_static/css/rtd-theme-fix.css',
7+
'_static/pygments.css']
8+
%}
9+
{% set script_files = script_files + [
10+
'_static/js/rtd-theme-extensions.js',
11+
'_static/js/versioning.js']
12+
%}

‎sphinx/_templates/versions.html

+39
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
{# Add rst-badge after rst-versions for small badge style. #}
2+
<div class="rst-versions" data-toggle="rst-versions" role="note"
3+
aria-label="versions">
4+
<span class="rst-current-version" data-toggle="rst-current-version">
5+
<span class="fa fa-book"> Read the Docs</span>
6+
v: {{ version }}
7+
<span class="fa fa-caret-down"></span>
8+
</span>
9+
<div class="rst-other-versions" id="version-selector">
10+
<script type="text/javascript">
11+
// NOTE: temporary variables not initiated so that they can be deleted
12+
13+
// path to a root file in the current version of the documentation
14+
version_path = "{{ pathto('') }}".split('/');
15+
// dirname of the root dir
16+
version_dir = version_path
17+
.splice(0, version_path.length - 1)
18+
.join('/');
19+
delete version_path;
20+
// relative path from the current version to the documentation root
21+
rel_path = '../../';
22+
// relative path from the current document to the documentation root
23+
var root_dir;
24+
if (version_dir) {
25+
root_dir = version_dir + '/' + rel_path;
26+
} else {
27+
root_dir = rel_path;
28+
}
29+
delete version_dir;
30+
delete rel_path;
31+
// the name of the current version of the documentation
32+
const current_version = "{{ version }}";
33+
// the name of the builder (i.e. html)
34+
const current_builder = "{{ builder }}";
35+
// the name of the current page
36+
const current_page_name = "{{ current_page_name }}";
37+
</script>
38+
</div>
39+
</div>

0 commit comments

Comments
 (0)