Assess how challenging it would be to update docs.amdc.dev to allow selecting between website versions

[elsevers]

Context

Related Issues / PRs:

• Add AMDC Firmware changes to implement the DCP AMDC-Firmware#500
• Add Daisy Chain Protocol Documentation and instructions on how to build and flash #154
• Release v3.0.0 AMDS#120

We are preparing a major release of the AMDC and AMDS. This will include accompanying changes to docs.amdc.dev, some of which will replace old content. It sure would be nice to be able to easily view previous releases of the website. We do a similar thing for the docs in our open source modeling codebase eMach -- see this menu in the lower right corner of the website:

eMach is hosted in a fundamentally different manner: using readthedocs.io.

docs.amdc.dev uses github pages (static html builds using sphinx).

Approach

Explore a roadmap to upgrading docs.amdc.dev to allow viewing different versions of the website.

Is this "easy" to do? Or... is it even feasible?

Right now, we need to march forward with releasing the next version of the AMDC/AMDS/docs.amdc.dev and likely cannot wait for this solution. BUT, are there things that we could/should be doing right now to make it easy to re-render the website prior to the changes we are about to merge in?

[mohamed-dek1]

There's an extension for Sphinx that provides support for releases and switching between them. It's called sphinx-multiversion and might be worth looking into. I don't know how much work is required to add this.

[AwesomeTornado]

I will look into this tonight and see what I can do.

[AwesomeTornado]

Not too hard, I have it working in a rough state currently.

[AwesomeTornado]

@elsevers This is actually a fairly easy change to make, provided we have some consistent way to label repository states which users should be allowed to switch to. The best way to do this is probably to publish a new release/create a new tag each time we want a new version, but we could also use carefully named branches to get the same effect.

You can find the changes I made for the rough example above here

[elsevers]

Thanks for digging in on this @AwesomeTornado!

Now, another conundrum: the project has several repos / version numbers:

• AMDC-Firmware (main versioning system we have been using, in classic major.minor.bug-fix form),
• AMDC-Hardware (has hardware revision letter that we also put on PCB silkscreen),
• AMDS (has its own major.minor.bug-fix)
• docs.amdc.dev (currently no versioning numbers).

I am scratching my head a bit on which version to have the docs.amdc.dev present as options for the user to select. I had been thinking we want this to be the AMDC-Firmware number. But this doesn't quite seem right, since we frequently modify content on the website independent of an AMDC-Firmware release. For example, right now, we are working on several PRs that add additional tutorials / application guidance. Probably better to introduce version numbering to docs.amdc.dev and somewhere have a map specifying which firmware AMDS and AMDC-Firmware version any docs version corresponds to? Hmm, this seems cumberson. I wonder if there is an analogy elsewhere in the open source community that would be helpful.

[AwesomeTornado]

I imagine the easiest way would be to have a rolling release set as the default site. This avoids needing to publish new versions for bugfixes and makes it easy to update.

Then, when new AMDC firmware is released, the rolling release can be tagged with the firmware revision it was made for. This freezes it in time and adds a link to it on the version switcher. The rolling release now becomes the documentation for the latest firmware revision, with any documentation branches designed for the new firmware merged at this point.
Note - The docs are not tagged with the firmware version until there is a new firmware version to replace it.

The current documentation already has multiple pages for hardware revisions, so unless this is causing issues I believe it would be a bad idea to incorporate that into our docs version switcher. Users will be able to switch between hardware revision independently from firmware revision, and we can tailor the hardware docs to the version. For example, old devices docs pages can have a warning added that says "This hardware revision is incompatible with your selected firmware revision."

As for the AMDS, it isn't quite as intuitive. Changes to the documentation would still be archived of course, but without some way of knowing which AMDC firmware revisions are compatible with which AMDS revisions it could be annoying to find the right version for your AMDS. In my opinion, this isn't much of an issue simply because the AMDS doesn't seem to get many updates. Currently, there has only ever been one major version update since release and it was done two years ago. The AMDS docs should remain relevant across many AMDC releases.

The only disadvantage in my eyes of using this tagging approach is that documentation for old firmware revisions cannot be updated, however I believe it is already an expectation that old firmware revisions will not continue receiving updated docs.

I would love to hear your thoughts @elsevers

[elsevers]

We decided to do it! Further progress tracked in #159