Version documentation

[lukehoban]

It would be nice if our docs were versioned so that users could navigate directly to the 1.8 docs. This may make sense initially just for API Docs (each of which versions independently).

[dstine]

Just adding my comment from Slack:

I find this feature incredibly useful, especially for emerging projects which are advancing rapidly, introducing significant new features (often independently transitioning from preview mode to GA), making selected backwards-incompatible changes, and so on. There is no substitute for direct navigation to e.g. the 1.7.1 Python SDK or 1.9.0 TS SDK, etc.

[ringods]

@lukehoban definitely have a look at Antora. If you want an example of a big site created with this tool:

• https://docs.couchbase.com
• Source entrypoint: https://github.com/couchbase/docs-site/blob/master/production-antora-playbook.yml

And a smaller example:

• https://terra-farm.github.io
• source entrypoint: https://github.com/terra-farm/terra-farm.github.io/blob/site/site.yml

The biggest advantage of this tool:

• works with docs out of multiple repositories
• uses branches and tags to mark the different versions
• uses AsciiDoc, which is a more extensive but fully standardised markup language.