Right now for the QPY documentation we manually write out a version history table. Where the entire contents are in the module docstring. This causes an awkward issue around release time where we need to update the table before we release. Especially when patch version releases are involved this can cause issues where we forget to update main but update the stable branch (or vice versa). For example, We completely forgot to update the version history table for 2.3.1, and 2.4.0 the update was almost overlooked an was one of the last commits backported to the stable/2.4.0 branch before release. Ideally we'd have a solution to automate the generation of the table to make it less error prone to keep it in sync.
There was a similar issue in Qiskit historically when we maintained a component version history table for the Qiskit metapackage. To solve this issue there I developed a custom sphinx extension that added a custom directive to look through all the git tags and pull out the component package versions from the requirements files. This automated the construction of the table at docs build time. This removed the need to manually update the docs for each release. The source of this extension can be found here:
https://github.com/Qiskit/qiskit-metapackage/blob/0.43.3/docs/versionutils.py
We could introduce a similar extension to the qiskit api docs for this use case too. Instead of parsing the requirements file though we can find the QPY version constants from the source files at each release tag and then use that to automate the table construction.
One thing we might want to change from the old metapackage extension though is not subprocess out to git anymore and maybe look at using dulwich instead (the library reno uses). That way we wouldn't depend on the git command to be installed and subprocessing out to look through the git history. In practice using git directly is probably fine since I struggle to think of a scenario someone is building the docs without using git, but it might be worth looking at alternatives
Right now for the QPY documentation we manually write out a version history table. Where the entire contents are in the module docstring. This causes an awkward issue around release time where we need to update the table before we release. Especially when patch version releases are involved this can cause issues where we forget to update main but update the stable branch (or vice versa). For example, We completely forgot to update the version history table for 2.3.1, and 2.4.0 the update was almost overlooked an was one of the last commits backported to the stable/2.4.0 branch before release. Ideally we'd have a solution to automate the generation of the table to make it less error prone to keep it in sync.
There was a similar issue in Qiskit historically when we maintained a component version history table for the Qiskit metapackage. To solve this issue there I developed a custom sphinx extension that added a custom directive to look through all the git tags and pull out the component package versions from the requirements files. This automated the construction of the table at docs build time. This removed the need to manually update the docs for each release. The source of this extension can be found here:
https://github.com/Qiskit/qiskit-metapackage/blob/0.43.3/docs/versionutils.py
We could introduce a similar extension to the qiskit api docs for this use case too. Instead of parsing the requirements file though we can find the QPY version constants from the source files at each release tag and then use that to automate the table construction.
One thing we might want to change from the old metapackage extension though is not subprocess out to git anymore and maybe look at using dulwich instead (the library reno uses). That way we wouldn't depend on the git command to be installed and subprocessing out to look through the git history. In practice using git directly is probably fine since I struggle to think of a scenario someone is building the docs without using git, but it might be worth looking at alternatives