Look into supporting multiple versions of documentation

[nickjer]

This is possible with https://robpol86.github.io/sphinxcontrib-versioning/index.html

[nickjer]

Seems it is not compatible with the latest Sphinx as documented here sphinx-contrib/sphinxcontrib-versioning#39

[nickjer]

Another option would be to build the different versions of the documentation in sub-directories of docs/.

• docs/latest/... => https://osc.github.io/ood-documentation/latest/...
• docs/v1.0/... => https://osc.github.io/ood-documentation/v1.0/...

Similar to:

• http://guides.rubyonrails.org/v4.1/
• http://guides.rubyonrails.org/v4.2/
• http://guides.rubyonrails.org/v5.0/

[nickjer]

If we do the above route though, maybe it is best to keep the builds within the branch gh-pages and include a build script that builds all the versioned branches.

[ericfranz]

I like this idea, following the Rails convention.

[ericfranz]

We should also have a /latest/ being a copy of the latest tag i.e. in rails example:

• http://guides.rubyonrails.org/v4.1/
• http://guides.rubyonrails.org/v4.2/
• http://guides.rubyonrails.org/v5.0/
• http://guides.rubyonrails.org/latest/ => same as http://guides.rubyonrails.org/v5.0/
• http://guides.rubyonrails.org/master/ => master branch HEAD
• http://guides.rubyonrails.org/some-branch/ => some-branch HEAD

[ericfranz]

With /latest/ we will be able to share this link.

[nickjer]

The /latest/ trick may require human intervention (e.g., creating a redirect in the /latest/index.html file to a version of our choosing).

Unless symlinks work, but I doubt it.

[ericfranz]

No symlinks and no redirect. Just cp -r from vX.Y to latest ( or better, rsync to mirror).

Would need routine to determine the latest release branch available and then match that against the current branch

[nickjer]

You would have to manually cp -r for the first time followed by a git commit and push, and then modify the Travis CI script in that defined latest branch to rm -fr latest and cp -r again every time that specific branch is modified.

[ericfranz]

So the psuedo code is:

if CURRENT_BRANCH == LATEST_VERSION
  rm -rf latest if latest.directory_exists?
  cp -r CURRENT_BRANCH latest
end

I don't see the manual step.

[ericfranz]

I guess you create and push a branch. The manual step is triggering Travis to run the build on that branch?

[nickjer]

Ah, you actually want the code to scan all the branch names and determine the latest version, I misunderstood the first time.

[nickjer]

This is now supported after many trial and errors.