Investigate Best Approach for Documentation Versioning in Quarto

[dweng0]

We need to establish the best method for versioning our documentation. One potential solution that I have been reviewing with @cmjc and @szemate is to leverage Git tags to determine the specific version of the generated code.

Proposed Approach:

Tag-based Versioning:

By using Git tags, we can automatically determine the version of the code being generated. @szemate recommends a script that runs git describe --tags as a good approach. These versions can then be reflected in the documentation. An alternative to tag based versioning would be to use the release/ tree to get the versions. However this would not show -all- versions (when comparing the tags with the release/ branches there are a lot more release tags). And so may not be what we want.

Quarto YAML File Update:

Using the data obtained from the tags (how?), we could generate a version-switching menu that would be placed in the header of the documentation site. This would allow users to easily navigate between different versions of the documentation.

We can modify the Quarto YAML file to include a drop-down list, allowing users to select the desired version of the documentation. This drop-down would display all available versions based on the tags. Example:

This above example is modified from the quarto site here
Which can be done by updating the _quarto.yml file with:

      - text: "Versions"
        menu:
          - text: "1.0.1"
            href: "path/to/1.0.1"
          - text: "1.0.2"
            href: "path/to/1.0.2"
          - text: "1.0.3"
            href: path/to/1.0.3

Versioning Through Folders:

The generated documentation could then be generated per version folder. For example, we could have a structure like contracts/v1.0.1/, contracts/v1.0.2/, contracts/v1/0/3 and so on. This would allow the version dropdown to "marry up" with the available versions based on the folder structure. There would be no technical debt with this approach as the code will be auto generated.

[cmjc]

Agree.

That sounds viable. Each publication of a new release version to master so to live is additive, writing a new folder and removing risk of overwriting an earlier version.

---

A refinement could be to have a latest version which is the default version selected when entering the site, and which is overwritten by the publication of a new release.

But you can just default to show the most recent version anyways, so probably not much value-add in that refinement... E.g. the solidity docs have a latest but https://docs.soliditylang.org/ resolves to display the current version tag. I.E. https://docs.soliditylang.org/en/v0.8.27/ .

[szemate]

Based on the above, my proposed solution is the following:

• Use git describe --tags to get the Autonity tag for which documentation is being generated. This is important because if we hard-code the tag in the docs repo then there is a chance that we accidentally generate the documentation for a different Autonity commit.
• The documentation is saved into version folders as described above.
• A Quarto plugin generates a version switcher based on the directories and the /latest endpoint (if possible? @cmjc).
• We don't touch the Quarto YAML

Alternatively, the doc generator script could edit the Quarto YAML and add the new version tag, but I'd prefer not to mix manually updated and auto-updated config files.

[aiman]

It seems essential to track and present the version of Autonity that the documentation corresponds to, both the written documentation as well as any generated documentation. This is probaly information we need to show in the footer of every page of the doc site.

Git tags are a good candidate for "version", but they are not ideal because they aren't immutable. To have a self-descriptive and unique identifier, we'd want to combine a committish object like a git tag or branch name (descriptive identifier) with the commit ID (unique identifier).

Having said that, I don't think it makes sense to be able to switch to older versions of the documentation. Autonity isn't a library or application that users can just pick and choose the version they want to use or read about. Generally, they can only make use of the live version of the protocol. They aren't going to be interested in previous versions (but they will want to see a CHANGELOG somewhere). Now there are some users may be interested in the docs for the "next" version of the protocol, but I imagine this is a very small audience limited to Autonity Core developers.

So here's my counter-proposal:

• track the current version of AGC corresponding to the docs
• AGC version should combine the current release version and commit ID v0.14.1-a5d0ecda7.
• render the AGC release version at the footer of every page
• we adopt the policy that the develop branch of docs.autonity.org tracks AGC develop branch
• the version of the develop branch will be develop-<COMMIT>
• no version drop-down
• no need for special paths

[szemate]

So here's my counter-proposal

It makes sense, implemented in #235

we adopt the policy that the develop branch of docs.autonity.org tracks AGC develop branch

Is it going to be updated manually or triggered by Autonity commits to develop?

[aiman]

Is it going to be updated manually or triggered by Autonity commits to develop?

I propose when the CI builds the site, it checks the branch of the docs.autonity.org site it's building, and there is special logic if it matches develop.

[aiman]

After discussion, it became clear that we don't have any need to go back to previous protocol versions.

But it would be great to be able to toggle between, the current live version of Autonity, and the version of Autonity corresponding to the state of the AGC develop branch.

To achieve two "versions" of the site, for example called current and develop, the question is how to access them:

• (A) we can have the toggle on the main set at docs.autonity.org, toggle using drop-down or buttons
• (B) we can have the two distinct sites, at different URLs