Qiskit
Patterns: dynamically generate Patterns index pages
In proposal 3 of https://github.com/Qiskit/documentation/pull/1294, each of the 4 patterns pages links out to the rest of the docs app. It provides an alternative organization than the tools-based approach. This is similar in spirit to Proposals 1 and 2.
It's way too hard to manually maintain both guides/_toc.json and that index page. We need some way to automatically generate the index. Note that the content above the index is manually written and needs to be preserved.
TBD what is the most sustainable way to do this. We need humans to tell us which pages go where: should they set a single file like generate-toc.py in https://github.com/Qiskit/documentation/pull/1294, which generates both _toc.json and the 4 index pages? Or should they set toc.json and a single file for the 4 patterns pages?
Regardless of implementation, we need lots of validation that we're not missing pages and all pages exist.
I imagine the patterns pages will be manually maintained but with a special comment saying where the auto-generation begins, and then we replace everything below that comment.
--
Update: the alternative is to have humans manually categorize things, but have a CI check that ensures pages are listed in the index page. We'd have an allowlist for pages that shouldn't be in workflows. This is probably the simpler approach because it avoids authors from having to use a generation script, which can be intimidating.
