Project

General

Profile

Actions

Feature #15138

closed

Support building of documentation for each stable release

Added by Peter Amstutz about 3 years ago. Updated over 2 years ago.

Status:
Resolved
Priority:
Normal
Assigned To:
Category:
-
Target version:
Start date:
06/12/2019
Due date:
% Done:

100%

Estimated time:
(Total: 0.00 h)
Story points:
2.0
Release relationship:
Auto

Description

We should support building multiple documentation versions (stable releases, master) and switching between them.

New jenkins job that takes a git ref (tag or 'master') and builds documentation for that version.

  1. git checkout target version
  2. build documentation
    1. parameter for target version, displayed on page header
    2. link to index page with all versions
  3. upload documentation to doc server at a target version directory
  4. regenerate index page with all versions + master
  5. upload index page
development tasks:
  • documentation lists selected version, dropdown menu links to every version
ops task:
  • jenkins job to generate documentation for target version (either as part of build pipeline or release process)

Subtasks 1 (0 open1 closed)

Task #15354: review 15138-version-our-documentationResolvedPeter Amstutz06/12/2019

Actions
Actions #1

Updated by Peter Amstutz about 3 years ago

  • Status changed from New to In Progress
Actions #2

Updated by Peter Amstutz about 3 years ago

  • Subject changed from Containerize documentation building to Containerize documentation building & support multiple versions
  • Status changed from In Progress to New
Actions #3

Updated by Peter Amstutz about 3 years ago

  • Description updated (diff)
Actions #4

Updated by Tom Morris about 3 years ago

  • Subject changed from Containerize documentation building & support multiple versions to Support building of documentation for each stable release
  • Description updated (diff)
Actions #5

Updated by Peter Amstutz about 3 years ago

  • Description updated (diff)
Actions #6

Updated by Peter Amstutz about 3 years ago

  • Description updated (diff)
Actions #7

Updated by Peter Amstutz about 3 years ago

  • Description updated (diff)
Actions #8

Updated by Peter Amstutz about 3 years ago

  • Target version changed from To Be Groomed to Arvados Future Sprints
  • Story points set to 2.0
Actions #9

Updated by Ward Vandewege about 3 years ago

  • Status changed from New to In Progress
  • Assigned To set to Ward Vandewege
  • Target version changed from Arvados Future Sprints to 2019-06-19 Sprint
Actions #10

Updated by Ward Vandewege about 3 years ago

The branch 15138-version-our-documentation at d50b8c00ec6aeb9175be4e4d8b58b684601eeda1 is ready for review.

Some config values to test with:

current_version: master
other_versions:
  - v1.4
  - v1.3
  - v1.2
  - master

I'm planning to only generate versions from 1.2, which is the first release we adopted a release branch for. I'm planning to only build documentation on the tip of each release branch (so, 1.2, 1.3, 1.4). I'm planning to cherry-pick the commits from this branch onto those three release branches.

To serve multiple versions of the docs, we're going to have an apache config along these lines:

  # The default documentroot is 'current' aka master
  DocumentRoot /var/www/doc.arvados.org/current/
  # More human friendly name
  Alias /master /var/www/doc.arvados.org/current

  # The releases each get a directory, and these directories
  # sit at the same level as the master directory. Map
  # them correctly here.
  RewriteEngine On
  RewriteCond %{DOCUMENT_ROOT}/../%{REQUEST_URI} -d [OR]
  RewriteCond %{DOCUMENT_ROOT}/../%{REQUEST_URI} -f
  RewriteRule ^/(v\d.\d.\d.*)$ /var/www/doc.arvados.org/$1

This is the 'dev' part of the above issue description. I'm planning to do the other parts as an expansion of our existing git hook, there's no need for a jenkins task here.

Actions #11

Updated by Ward Vandewege about 3 years ago

I've pushed a new 3a080e9c0f670dcedd42229809e682008505b4db on branch 15138-version-our-documentation that moves the dropdown to the right, which was the only (verbal) review comment by Peter.

Actions #12

Updated by Ward Vandewege about 3 years ago

  • Status changed from In Progress to Resolved
Actions #13

Updated by Peter Amstutz over 2 years ago

  • Release set to 22
Actions

Also available in: Atom PDF