Feature #15138

Support building of documentation for each stable release

Added by Peter Amstutz 3 months ago. Updated about 1 month 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

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

Task #15354: review 15138-version-our-documentationResolvedPeter Amstutz

Associated revisions

Revision 8ad5eb9a
Added by Ward Vandewege about 1 month ago

Merge branch '15138-version-our-documentation'

refs #15138

Arvados-DCO-1.1-Signed-off-by: Ward Vandewege <>

Revision 00015811 (diff)
Added by Ward Vandewege about 1 month ago

Keep relative URL when switching between versions in our documentation.

refs #15138

Arvados-DCO-1.1-Signed-off-by: Ward Vandewege <>

Revision 993a5c4d (diff)
Added by Ward Vandewege about 1 month ago

Keep relative URL when switching between versions in our documentation.

refs #15138

Arvados-DCO-1.1-Signed-off-by: Ward Vandewege <>

Revision b4bda0c1 (diff)
Added by Ward Vandewege about 1 month ago

Keep relative URL when switching between versions in our documentation.

refs #15138

Arvados-DCO-1.1-Signed-off-by: Ward Vandewege <>

Revision fc4050de (diff)
Added by Ward Vandewege about 1 month ago

Keep relative URL when switching between versions in our documentation.

refs #15138

Arvados-DCO-1.1-Signed-off-by: Ward Vandewege <>

History

#1 Updated by Peter Amstutz 3 months ago

  • Status changed from New to In Progress

#2 Updated by Peter Amstutz 3 months ago

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

#3 Updated by Peter Amstutz 3 months ago

  • Description updated (diff)

#4 Updated by Tom Morris 3 months ago

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

#5 Updated by Peter Amstutz 3 months ago

  • Description updated (diff)

#6 Updated by Peter Amstutz 3 months ago

  • Description updated (diff)

#7 Updated by Peter Amstutz 3 months ago

  • Description updated (diff)

#8 Updated by Peter Amstutz 3 months ago

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

#9 Updated by Ward Vandewege about 1 month ago

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

#10 Updated by Ward Vandewege about 1 month 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.

#11 Updated by Ward Vandewege about 1 month 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.

#12 Updated by Ward Vandewege about 1 month ago

  • Status changed from In Progress to Resolved

Also available in: Atom PDF