Versioned documentation

[victorb]

As APIs and commands sometimes looks different from version to version, the user should be able to switch the API/commands docs between different versions.

[Mr0grog]

This would be super valuable. Since all the implementations move at different speeds and things are broken up into a lot of modules, we’ll need each module to have its own set of versioned docs instead of versioning all the reference docs together.

@lgierth I know you care a lot about the URLs for these docs and how they mirror godoc.org, but it doesn’t seem like there’s any concept of versioning there. Do you have thoughts on how versions would fit into the URL?

We have:

/{language}/pkg/{published package name}/{path into package}

# So for example:
/go/pkg/go-ipfs/core/coreapi/interface

I’m thinking this goes after {published package name} in the format vX.Y.Z:

/{language}/pkg/{published package name}/{version}/{path into package}

# So for example:
/go/pkg/go-ipfs/v0.4.17/core/coreapi/interface

The version string stable (or current?) and next could be symlinks to the current release and top-of-tree, respectively.

Aside from answering the URL question, I think the things that have to happen here are:

• Define a structure for where the output lives on disk
• Update the makefile and scripts to put things in the right place
• Probably stop ignoring generated API docs in Git. As we accumulate versions, it’s going to be a real pain to regenerate the docs for every old version of every package.
• Design and implement UI for switching versions of docs

Then we need to figure out how this works for CLI & HTTP API docs. Since those are supposed to cover both JS & Go implementations, they’re more complicated. I propose we simply treat those like the above and version them with the Go implementation at first because they are just generated from the Go code right now anyway. Better solutions can be part of #69 (Re-think HTTP API Documentation).

[meiqimichelle]

See also ipfs-cluster/ipfs-cluster-website#88 (Post-v1 cluster website should provide versioned documentation )

[jessicaschilling]

This is a very good point that we shouldn't lose track of when spec-ing our next-generation docs platform. @ericronne and @cwaring -- can you please address in #195 and #197 as appropriate? Thank you!

[jessicaschilling]

Closing this issue since it's captured in our requirements lists for new docs platform at https://hackmd.io/qCel8CPkRtCZsAA-Oxeupw?both and https://docs.google.com/spreadsheets/d/1YJ8yuzoNeunVr3ftvm7x2nIKsj7IlTrsfuy71ZnGg6Y/edit#gid=785339355