Initial audit of header hierarchy for all module API pages #942
Comments
This was referenced Mar 1, 2024
github-merge-queue bot
pushed a commit
that referenced
this issue
Mar 4, 2024
Closes #932. We decided: 1. We are going to keep showing h1s for class and function pages. It's useful because they have non-trivial code at the top level, like their docstring and constructor. It's nice to have the quick way to access the value. 2. For now at least, we won't show h4s in the module pages. There are 8 module pages in the current API docs that use h4s. I think showing h4s improved ~3 of them, and made ~5 worse. So, for now, let's not include them. This can be revisited, especially after #942. This regens all APIs but reverts dev docs, which have unrelated changes and will be regenerated in a dedicated PR.
Eric-Arellano
added a commit
to Qiskit/qiskit-ibm-runtime
that referenced
this issue
Apr 30, 2024
Closes Qiskit/documentation#1240 and partially addresses Qiskit/documentation#942 for runtime. ## Reduces `transpiler` modules Before: | module | status | | --- | --- | | qiskit.transpiler | only links to `passes` | | qiskit.transpiler.passes | only links to `basis` and `scheduling` | | qiskit.transpiler.passes.basis | empty, should link to ConvertIdToDelay but doesn't | | qiskit.transpiler.passes.scheduling | useful | Now: | module | status | | --- | --- | | qiskit.transpiler.passes | links to `ConvertIdToDelay` and `scheduling` | | qiskit.transpiler.passes.scheduling | useful | This saves the user clicks. Now each page is useful enough to stand on its own. This is what the index page now looks like: <img width="689" alt="Screenshot 2024-04-30 at 4 20 41 PM" src="https://github.com/Qiskit/qiskit-ibm-runtime/assets/14852634/8cdefee6-b8a7-491d-be32-aeb974fce92b"> This change assumes that we will not add new modules to `qiskit.transpiler` for some time, such as `qiskit.transpiler.my_module`. If we do eventually add a new module, then we can easily revert `transpiler.rst` to point to `qiskit_ibm_runtime.transpiler` again. This change also assumes that we won't lots of new APIs to `qiskit.transpiler.passes.basis`. If we do, we would want to consider going back to `qiskit.transpiler.passes.basis` being its own standalone page. We can do that easily if necessary in the future. ## Improves header hierarchy ### Options Before, we were using bold text to act like headers. Instead, we should be using proper headers for styling, SEO, and accessibility (screen readers). ### `qiskit_ibm_runtime.transpiler.passes.scheduling` This PR moves the `classes` list to be higher in the file and fixes some of the other headers to higher heading levels. ## Removes unused docstrings The `utils` module is not exposed, and Kevin said it should not be since it's internal. So I deleted its docstring to make this more clear.
Eric-Arellano
added a commit
to Eric-Arellano/qiskit-ibm-runtime
that referenced
this issue
May 1, 2024
Closes Qiskit/documentation#1240 and partially addresses Qiskit/documentation#942 for runtime. ## Reduces `transpiler` modules Before: | module | status | | --- | --- | | qiskit.transpiler | only links to `passes` | | qiskit.transpiler.passes | only links to `basis` and `scheduling` | | qiskit.transpiler.passes.basis | empty, should link to ConvertIdToDelay but doesn't | | qiskit.transpiler.passes.scheduling | useful | Now: | module | status | | --- | --- | | qiskit.transpiler.passes | links to `ConvertIdToDelay` and `scheduling` | | qiskit.transpiler.passes.scheduling | useful | This saves the user clicks. Now each page is useful enough to stand on its own. This is what the index page now looks like: <img width="689" alt="Screenshot 2024-04-30 at 4 20 41 PM" src="https://github.com/Qiskit/qiskit-ibm-runtime/assets/14852634/8cdefee6-b8a7-491d-be32-aeb974fce92b"> This change assumes that we will not add new modules to `qiskit.transpiler` for some time, such as `qiskit.transpiler.my_module`. If we do eventually add a new module, then we can easily revert `transpiler.rst` to point to `qiskit_ibm_runtime.transpiler` again. This change also assumes that we won't lots of new APIs to `qiskit.transpiler.passes.basis`. If we do, we would want to consider going back to `qiskit.transpiler.passes.basis` being its own standalone page. We can do that easily if necessary in the future. ## Improves header hierarchy ### Options Before, we were using bold text to act like headers. Instead, we should be using proper headers for styling, SEO, and accessibility (screen readers). ### `qiskit_ibm_runtime.transpiler.passes.scheduling` This PR moves the `classes` list to be higher in the file and fixes some of the other headers to higher heading levels. ## Removes unused docstrings The `utils` module is not exposed, and Kevin said it should not be since it's internal. So I deleted its docstring to make this more clear.
kt474
pushed a commit
to Qiskit/qiskit-ibm-runtime
that referenced
this issue
May 1, 2024
Closes Qiskit/documentation#1240 and partially addresses Qiskit/documentation#942 for runtime. ## Reduces `transpiler` modules Before: | module | status | | --- | --- | | qiskit.transpiler | only links to `passes` | | qiskit.transpiler.passes | only links to `basis` and `scheduling` | | qiskit.transpiler.passes.basis | empty, should link to ConvertIdToDelay but doesn't | | qiskit.transpiler.passes.scheduling | useful | Now: | module | status | | --- | --- | | qiskit.transpiler.passes | links to `ConvertIdToDelay` and `scheduling` | | qiskit.transpiler.passes.scheduling | useful | This saves the user clicks. Now each page is useful enough to stand on its own. This is what the index page now looks like: <img width="689" alt="Screenshot 2024-04-30 at 4 20 41 PM" src="https://github.com/Qiskit/qiskit-ibm-runtime/assets/14852634/8cdefee6-b8a7-491d-be32-aeb974fce92b"> This change assumes that we will not add new modules to `qiskit.transpiler` for some time, such as `qiskit.transpiler.my_module`. If we do eventually add a new module, then we can easily revert `transpiler.rst` to point to `qiskit_ibm_runtime.transpiler` again. This change also assumes that we won't lots of new APIs to `qiskit.transpiler.passes.basis`. If we do, we would want to consider going back to `qiskit.transpiler.passes.basis` being its own standalone page. We can do that easily if necessary in the future. ## Improves header hierarchy ### Options Before, we were using bold text to act like headers. Instead, we should be using proper headers for styling, SEO, and accessibility (screen readers). ### `qiskit_ibm_runtime.transpiler.passes.scheduling` This PR moves the `classes` list to be higher in the file and fixes some of the other headers to higher heading levels. ## Removes unused docstrings The `utils` module is not exposed, and Kevin said it should not be since it's internal. So I deleted its docstring to make this more clear.
Eric-Arellano
changed the title
This was referenced May 1, 2024
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Like Qiskit/qiskit#11923, but for all the other modules. We want to look for a few things:
Note that we should never use more than one h1 on module pages; don't try to improve the header hierarchy that way.
Module pages can be identified by searching for
python_api_type: module. This shouldn't be a problem on function and class API pages, which are much more auto-generated than human-written.--
The text was updated successfully, but these errors were encountered: