[ckan-dev] Readthedocs and CKAN documentation versions

Mon May 6 13:51:09 UTC 2013

Hey all,

The way we're currently doing this is broken. Can we come up with
something better?

We currently create a git tag for each CKAN release, and have RTD build
a version of the docs from each tag. This doesn't work very well,
because we don't create the git tag for a version until that version is
finally released, so right now for example, it's not possible to get the
docs for 2.0 beta.

Would mapping the release branches, rather than tags, to RTD docs
versions work better? That way, as soon as we branch for a release,
the docs for that release appear on RTD. Then all we need to do, is make
sure it says "beta" somewhere prominent in the docs, until we decide
that the release is final.

This would mean URLs to old CKAN 1.x releases would change, they'd now
be /en/release-v1.8 instead of /en/ckan-1.8. I think we could get RTD to
still build the docs for the ckan-1.8 tag but build them "privately", so
ckan-1.8 wouldn't appear in the list of versions at the bottom of the
page (only release-v1.8 would) but any links out there to /en/ckan-1.8
would still work.

Because we name our release branches like release-v2.0 this would,
unfortunately, mean that the URL to the docs for a CKAN release would be
like docs.ckan.org/en/release-v2.0, which is even worse than the
current, tag-based URLs (docs.ckan.org/en/ckan-2.0/).

Unfortunately I don't think there's anything we can do about this,
unless we change how we name our branches. If the 2.0 release branch was
just called 2.0 for example, then it'd be docs.ckan.org/en/2.0, which is
what you'd want as your docs URL, but possibly not what you'd want for
your branch name.

Related, I don't think the "latest" docs should say a version number
like v2.1a as they currently do. It should just say "latest development
version" or something.