Merge docs into main source tree, automatically deploy them and allow switching between versions
When the main build succeeds, the docs are built and deployed in a separate job. The built docs are then SCP'ed to the deployment location, which has the following structure:
deploy_dir/
versions.json
1.8.0-SNAPSHOT/
1.8.0/
1.7.6/
The build script generates a small JSON file, versions.json
that defines the versions of the docs that will be available to switch between. This is necessary because it is not possible to get a directory listing on the filesystem in the web browser from JavaScript (for security reasons):
{
"release": "1.8.0",
"snapshot": "1.8.0-SNAPSHOT",
"versions": [
"1.7.6",
"1.8.0",
"1.8.0-SNAPSHOT"
]
}
A small piece of JavaScript reads versions.json
and uses it to populate the version switcher. When a user switches versions, they are redirected to the index page of the correct subdirectory, e.g. deploy_dir/1.8.0
.
Note that only the docs for the current version are built - it is assumed that previous versions of the docs still exist in the deployment location.