doc: investigate versioned readthedocs

[matzf]

Currently we only have the "latest" documentation published on https://docs.scion.org, corresponding to the master branch. It could be useful to enable versioned documentation, as this could avoid potential confusion in reference manuals relating to configuration files, command line flags etc, as well as for tutorials that might only work with a particular version.

Considerations

• make stable the default?
• automatically refer to corresponding release (or nightly build for "latest") in installation instructions / in tutorial?

See

• https://me-readthedocs.readthedocs.io/en/stable/versions.html
• https://me-readthedocs.readthedocs.io/en/stable/automation-rules.html

[oncilla]

We have enabled this in our public documentation, and it works quite well.

One thing that you should keep in mind though is that improvements to the docs either need to be back ported, or will not be available on a particular version of the docs. Bigger restructures of the docs can come with a high tax on maintenance due to back porting.

In any case, I think it is worth while to provide versioned docs!

[matzf]

Update: last week I've enabled version v0.10.0. For now I'm planning to (manually) keep the last couple releases active in addition to "latest". I decided not to enable "stable" for now, as it's identical to the only other active version v0.10.0 and thus would have seemed needlessly confusing.

As our docs includes both developer and user facing documentation, making "stable" the default does not seem like the obviously right choice; for user docs, "stable" makes sense but developer docs should generally only be viewed on "latest". Splitting the documentation tree into separate projects just to accommodate these different versioning preferences seems overkill though. I think a good compromise could be to keep "latest" the default but put a warning banner on user-documentation pages with changes since the last release. I haven't found an easy way to achieve this yet, but it clearly does seem doable. (Side note: even the generic version warning banner is currently not generally available, it appears there have been changes to this feature that are now in beta on readthedocs).

--

Update 2:

I just came across a nice example of a banner that would make sense for our "latest" documentation version: