Release notes folder for Qiskit SDK is very large in table of contents

[Eric-Arellano]

Would it make any sense to stop having release-notes be a collapsible folder and instead only have it be the index page /api/qiskit/release-notes?

[Eric-Arellano]

For this issue focused on the left ToC, we decided that we should group into subfolders:

• v0.x
• v1.x
• v2.x

We should also rename the TOC entries for the minor releases to have v as their prefix, like v2.0. (Do not change any URLs)

[gracelindsell]

@Eric-Arellano designs are completed and can be found here

[Eric-Arellano]

This is the design. Very similar to https://github.com/Qiskit/documentation/issues/2941, such as same order of versions and grouping by major version:

The main change is that this needs to update the _toc.json file for every folder in api/qiskit.

Step 1

We have this code to generate the _toc.json:

https://github.com/Qiskit/documentation/blob/c5780a96bdb96401f9bbfea8fc34791c6ebd9a91/scripts/js/lib/api/generateToc.ts#L232-L247

Lines 240-246 are what we need to change.

This code should use the new function from https://github.com/Qiskit/documentation/pull/3902 to group by major versions. Then, have TOC entries like:

{"title": "v2", "children": [
  {"title": "v2.1", "url": "/docs/api/qiskit/release-notes/2.1"}, 
  {"title": "v2.0", "url": "/docs/api/qiskit/release-notes/2.0"}
]}

You should make generateReleaseNotesEntry public so that you can write unit tests for it. Reminder to use Pkg.mock() to help with writing the unit tests.

Then test that things are actually working in the real world by running npm run gen-api -- -p qiskit -v 2.1.2 and checking that the _toc.json file changes are expected. If that is all working, commit the change. Then run npm run regen-apis -- -p qiskit - you should see the _toc.json updated for every version, i.e. they should all be using the same new format.

Step 2

TODO. I'm still thinking of the best approach. We need to rework updateHistoricalTocFiles in releaseNotes.ts.

(Note for Eric: think about storing in-memory the new release notes TOC for the current version, which should already be figured out. Then overwrite the TOC for all historical versions, vs. right now only appending the current version. Land this as a prefactor.)

[Eric-Arellano]

Thanks @gracelindsell and @GantaRoja