Help Wanted: Implement versioned product documentation

[cwarnermm]

Context

Currently, Mattermost product documentation follows a "latest release" content approach rather than a versioned approach.

This means that:

• all documentation content is considered applicable to the latest release, unless otherwise noted.
• documentation site visitors can't select their specific Mattermost release version to focus on a filtered view of release-specific documentation details.

Target audience

All users, and particularly users looking for product documentation applicable to their specific Mattermost release version.

Goal

Enable the ability for documentation visitors to select their specific Mattermost release version from a selector added to the Sphinx Theme (Furo).

Once a specific release is selected, the product documentation displayed updates to reflect that release.

Delivery Expectations

• 1 PR with all proposed changes
• Comment in the PR to request a generated preview of your work. The Docs team will add the appropriate labels to your PR.
• Language support: English only
• Support current release and 2 ESR releases only.

Tech needed

• Sphinx & conf.py configuration
  • Sphinx provides a UI version selector that can be enabled; is more UI work required?
• GitHub versioned docs branches

Repository

mattermost/docs

Get Help

Join the Mattermost Docs team on the Mattermost Community Server in the ~Documentation Working Group channel to discuss this ticket, or feel free to comment in this docs ticket

[cwarnermm]

@neflyte - Would you be open to outline the effort involved to version the Mattermost product docs based on your initial investigation? Contributors interested in this ticket would benefit from understanding the Sphinx-specific configuration needed to surface a version selection option that returns version-specific docs on demand (based on release data in GitHub).

[neflyte]

This one is a little complicated.

The versioning capabilities that we've seen so far are part of ReadTheDocs instead of Sphinx. Furthermore, the versioning capability is meant for the ReadTheDocs hosted solution and not for standalone docs. I suspect the early authors of the MM product docs discovered this and decided to remove some of the implementation that could not be used; hence a customized versions.html template.

I experimented with this today and found a few things:

• Further customization of the versions.html template is required to combine versioning with the existing "edit in github" changes
• The conf.py file needs to be updated with a list of existing versioned docs and where there are located; this info gets rendered in the version box at the bottom of the LHS
• It is not possible to specify existing docs versions on the CLI using the RTD implementation
  • I suspect RTD injects their own configuration into conf.py when their service builds docs
  • It would be possible to specify existing versions on the CLI using a custom implementation of versioning
• The SRE team, or whomever is responsible for hosting, would need to be engaged to adjust build pipelines as necessary to deploy built docs into the correct location
  • This would take into account existing deployed docs versions

Needless to say, there are a few moving parts.

For reference, the RTD versioning implementation wants its versions and downloads variables defined in conf.py like so:

html_context = {
    # ...
    versions = [("1.0","https://url.to/1.0"),("1.1","https://url.to/1.1")]
    downloads = [("PDF","https://url.to/docs.pdf")]
    # ...
}