Module API pages should not include h1 in their page table of contents
#932
Comments
|
All module pages with h4s: |
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.
frankharkins
pushed a commit
to frankharkins/documentation
that referenced
this issue
Jul 22, 2024
Closes Qiskit#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 Qiskit#942. This regens all APIs but reverts dev docs, which have unrelated changes and will be regenerated in a dedicated PR.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
We hardcode that API docs always should show
h1 - h3in the right table of contents, whereas the default is to only showh2 - h3.documentation/scripts/lib/api/addFrontMatter.ts
Line 34 in c7bbfb1
We do this because it's useful for API class pages, where it's nice to have the class name show up in the right table of contents. That's useful as a way to quickly jump to the class definition because it is non-trivial, like including the constructor and class docstring.
However, that is a bad default for module pages like https://docs.quantum.ibm.com/api/qiskit/exceptions where the page title is not very informative.
Instead, for module pages, we should keep the default of h2 being the min level to show. We should also show h4 because these module pages often have nested information that is worth rendering, although we need to preview a few pages to see what this looks like and confirm it's a good heuristic.
The text was updated successfully, but these errors were encountered: