[ EPIC ] Adding Transparency to the Transpiler

[kaelynj]

URL, if applicable

No response

Describe the new content you are requesting.

From the discussion in #878, I've identified a few topics for new pages/edits to other pages that I will work on adding in to the transpile section. I'll keep track of the list of changes using this issue and will expand the list as needed. Feel free to add suggestions or comments.

- [ ] https://github.com/Qiskit/documentation/issues/1071
- [ ] https://github.com/Qiskit/documentation/issues/1075
- [ ] https://github.com/Qiskit/documentation/issues/1078
- [ ] Edit the `qiskit.synthesis` [overview docstring](https://docs.quantum.ibm.com/api/qiskit/synthesis) to make more clear what the module is designed for (from what I understand it's the "engine" powering some/all of the transformation passes, among other things).
- [ ] Expand introduction to the `qiskit.transpiler.passes` [overview section](https://docs.quantum.ibm.com/api/qiskit/transpiler_passes) in the API docs.
- [ ] https://github.com/Qiskit/documentation/issues/1077
- [ ] https://github.com/Qiskit/documentation/issues/891

If this new content request is accepted, do you want to write the content?

I will write a draft of the proposed content

[Eric-Arellano]

Reorganize the items on the left sidebar of the qiskit.transpiler.passes API docs to match the section ordering found in its overview page (@Eric-Arellano is this possible by making a custom ordering for this part of the API docs? Or would the API docs themselves need to be edited?)

It's not possible without adding substantial complexity to the docs generation script. If we weren't to make changes to the API script, then we'd need to reorganize the APIs to live in submodules. But that changes the actual import paths for end users in a bad way, so it's a non-starter.

If this is really important to change the left sidebar, we can consider it. But I'd bias against it since the script is already pretty complex.

[kaelynj]

It's not possible without adding substantial complexity to the docs generation script. If we weren't to make changes to the API script, then we'd need to reorganize the APIs to live in submodules. But that changes the actual import paths for end users in a bad way, so it's a non-starter.

If this is really important to change the left sidebar, we can consider it. But I'd bias against it since the script is already pretty complex.

Yeah I figured this might be the case. From a user perspective, it's quite unclear how to navigate these API pages unless you go directly to the Overview page where it's TOC groups the related pages together. Ordering them into sections instead of one long alphabetical list of pages would make navigating to particular types of passes significantly easier.

I totally understand this would be tricky, but I think it's an important enough quality of life improvement that we should consider it.