Docs versioning

[ES-Alexander]

Currently we don't have documentation for different versions of our softwares/firmwares.

It seems relevant to at least document any versions that are live and available (e.g. ArduSub Beta and Development, not just Stable, and QGC 4.1.4 as well as 4.0.5, and same for companion when a new version is released). It would likely also be valuable to include change-logs in our docs if possible instead of just links to the respective github pages, as well as 'last updated' dates for firmware builds.

Versioned docs also means once we get the docs aligned with the current feature set we can have docs releases that match other feature releases, which helps make sure they actually stay up to date (instead of the current thing where probably there are a bunch of things in the docs that we don't even know are there). I'm curious as to whether git submodules are relevant to that kind of feature, or whether it's best left out and handled in other ways.

If possible I'd like to have a version-selector for the relevant software pages, which allows us to specify new information for each section as relevant, but by default 'falls back' to the most recently available docs for each section. That way we don't need to fully duplicate our docs for every version, but instead just implement and specify the changes. Not sure how that's best handled - I'll need to look into it. It may be possible to build docs from a set of repo releases, but that then means updating any old docs that were wrong would need to also update those release tags, which could (maybe) be problematic. It's also important to somehow ensure that some versions are tied together (e.g. QGC and ArduSub have some version compatibility requirements (particularly related to parameters), and there are also some between companion and ArduSub (e.g. for the /dev/autopilot change)).

[ES-Alexander]

Assuming #229 is agreed upon, we should be able to

• separate the custom docs for each software into its own repo (branches for major/minor versions, tags for patches/releases)
• have multiple submodules of each software-docs repo (e.g. developers/qgroundcontrol/4.0.5/..., developers/qgroundcontrol/4.1.4/...)
• have 'latest' available for each version, either as a submodule that's the same as the latest one, or as an auto-redirected link (via .gitbook.yaml?)
• changing versions could be accomplished by a html select element which has a JS onChange function that replaces the thing after software-name/<replace-this>/... with the new selected version
• the relevant select element should be defined outside its respective submodules, and preferably auto-included with a software-directory-wide header file, maybe using something like gitbook-plugin-layout or similar (which we should probably already be using - our footers are very inconsistent)
• if we assume software docs files will be maintained across versions then the sidebar could also link dynamically based on the current url version, or fall back to the latest version if no current version exists (e.g. if going from companion to QGC)
• not sure whether the sidebar can be dynamically updated to suit a particular version, so that's preferably avoidable if possible (good to at least keep the same files if we can)
• it would be nice if when changing softwares we're able to automatically go to the most recent suitable one (e.g. when changing from ArduSub to QGC, since only some specific versions are compatible together), but that would likely get somewhat complicated
• an alternative to the auto approach to url-hacking could be to use cookies for the latest selected docs version of each software, but I'm not sure how complicated that would be (in general, or in the gitbook context)

[ES-Alexander]

Note QGC is the priority at this point (4.1.4 is stable but undocumented), and preferably both QGC and ArduSub can have clean docs versioning available before companion 1 is released, which should hopefully then be a not too difficult addition :-)