[docs]Maintain separate docs for different releases

[tshirtman]

This will cause CI to build docs for specific branches when they are
pushed to, and to copy the result into a subdirectory of the docs/
directory, instead of the root. The task will also update a
"versions.json" file, for the pages to be able to display/select other
versions.

The doc template is changed slightly to display a select field on top
of the quick search, using some js to fill the versions from the
generated versions.json file, and to change url when a different version
is selected.

This has been tested with a local server, trying to emulate the doc
structure, but the CI part hasn't been really tested.

Known Issues:

• the version.json file contains all versions configured to build, but
  the doc for these might not have been generated yet, which would
  result in 404 errors.
• the logic doesn't know if the current page of the doc exists for the
  selectable versions, so this will also result in 404 errors when
  switching to a version that didn't have the current doc page..
• the url manipulation logic is a bit dirty, as it assumes that the path
  is always of the form of /docs//….
• theming could certainly be slightly improved.

[dessant]

The changes could be backported to the branches for which doc generation is needed. The server will need a redirection from /docs/* to /docs/stable/* when this gets merged.

[tshirtman]

As discussed in private with @dessant there is a disambiguation issue with url redirection with that setup, there seem to be a lack of really nice solutions to this (nginx knowing about all the existing versions would be hacky and a maintenance burden, js stubs to redirect in all the old pages would be sad for a lot of reasons, and letting all the old urls become dead links would be really sad too), so i think the only remaining solution would be to change the url more, here are a few options i could think of.

• /docs/version/{version}/path/to/page
• /docs/v{version}/path/to/page
• /doc/{version}/path/to/page (note the lack of "s" in "doc", which is good enough to distinguish old and new format)

I don't think too much bikeshedding is needed on this, i think my preference goes to the first (for clarity) and third one (for concision), but maybe someone will propose a better alternative, we can give it a week or so, and then take a decision, as it'll certainly have an impact on the visibility/discoverability of the doc, which is pretty important for the project.

[dessant]

I'm also ok with both the first and third options, though the third one has started to grow on me.

[akshayaurora]

👍 for /doc/...

How ever I would like to propose to choose a time to delete the existing ones. There are a lot of stale files that still get served up in google with a high enough priority to be in the top 3.

Deleting old docs would be necessary to avoid such issues.

[dessant]

The rsync params should ensure that the docs folder is overwritten, without outdated files left behind. Could you share an example of a stale file from the docs folder?

[tshirtman]

I think that's a separate issue, it seems we agree on /doc/ i'll amend the PR to do that.

[tshirtman]

ready for review i think.

[matham]

The travis changes look ok. Not sure about the css/js. Also, please add that DOC_VERSIONS needs to be updated to the release checklist.

[dessant]

How will DOC_VERSIONS be translated in practice? It seems those stable- prefixes become part of the version.

[dessant]

Maybe we could rename stable-{version} branches to {version} or v{version}.

[dessant]

Or we could have a dict with branch names mapped to version names. For example, dev would be a more meaningful version to show in the selector widget and to have in the URL, instead of master.

{
  "stable-1.10": "v1.10.0",
  "stable": "stable", 
  "master": "dev"
}

[matham]

The standard way is to prefix the version number with a v, rather than just having the version number.

[tshirtman]

release doc updated.

[dessant]

Ok, so going forward, these will be the URL variations:

/doc/stable/path/to/page
/doc/master/path/to/page
/doc/v{version}/path/to/page

/docs/path/to/page will redirect to /doc/stable/path/to/page.

[tshirtman]

I think we can wait after the merge and tests to setup the redirection :).