Skip to content

Merge docs into main source tree, automatically deploy them and allow switching between versions

Justin Lewis Salmon requested to merge docs into master

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.jsonthat 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.

Merge request reports