-
Notifications
You must be signed in to change notification settings - Fork 90
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Fix unnecessary h1 header in module pages generated by autosummary #1272
Comments
Eric-Arellano
added a commit
to Qiskit/qiskit-ibm-runtime
that referenced
this issue
May 2, 2024
Before, `qiskit_ibm_runtime.transpiler.passes.scheduling` was autogenerated by `autosummary` rather than being manually created like we normally do in `apidocs/`. This had two issues: 1. The module does not show up in the API index page https://docs.quantum.ibm.com/api/qiskit-ibm-runtime, even though it shows up as top-level in the doc app's left table of contents 2. The header hierarchy is messed up due to an autosummary quirk that I could not figure out Qiskit/documentation#1272 Using a dedicated page fixes both of these problems. I named the file `qiskit_ibm_runtime.transpiler.passes.scheduling.rst` to preserve the previous URL we had for the module. (Technically, Sphinx now puts the HTML file in the `apidocs/` folder rather than `stubs/`, but the docs app doesn't care.) This PR also removes the override of the `module.rst` template. We shouldn't end up using it anymore. Regardless, our version is out-of-date compared with the default and we didn't have any substantial changes.
Eric-Arellano
added a commit
to Eric-Arellano/qiskit-ibm-runtime
that referenced
this issue
May 2, 2024
Before, `qiskit_ibm_runtime.transpiler.passes.scheduling` was autogenerated by `autosummary` rather than being manually created like we normally do in `apidocs/`. This had two issues: 1. The module does not show up in the API index page https://docs.quantum.ibm.com/api/qiskit-ibm-runtime, even though it shows up as top-level in the doc app's left table of contents 2. The header hierarchy is messed up due to an autosummary quirk that I could not figure out Qiskit/documentation#1272 Using a dedicated page fixes both of these problems. I named the file `qiskit_ibm_runtime.transpiler.passes.scheduling.rst` to preserve the previous URL we had for the module. (Technically, Sphinx now puts the HTML file in the `apidocs/` folder rather than `stubs/`, but the docs app doesn't care.) This PR also removes the override of the `module.rst` template. We shouldn't end up using it anymore. Regardless, our version is out-of-date compared with the default and we didn't have any substantial changes.
This was referenced May 2, 2024
kt474
pushed a commit
to Qiskit/qiskit-ibm-runtime
that referenced
this issue
May 2, 2024
Before, `qiskit_ibm_runtime.transpiler.passes.scheduling` was autogenerated by `autosummary` rather than being manually created like we normally do in `apidocs/`. This had two issues: 1. The module does not show up in the API index page https://docs.quantum.ibm.com/api/qiskit-ibm-runtime, even though it shows up as top-level in the doc app's left table of contents 2. The header hierarchy is messed up due to an autosummary quirk that I could not figure out Qiskit/documentation#1272 Using a dedicated page fixes both of these problems. I named the file `qiskit_ibm_runtime.transpiler.passes.scheduling.rst` to preserve the previous URL we had for the module. (Technically, Sphinx now puts the HTML file in the `apidocs/` folder rather than `stubs/`, but the docs app doesn't care.) This PR also removes the override of the `module.rst` template. We shouldn't end up using it anymore. Regardless, our version is out-of-date compared with the default and we didn't have any substantial changes.
github-merge-queue bot
pushed a commit
that referenced
this issue
May 2, 2024
Pulls in the fix for #1272 to Runtime. Runtime now also calls its API index page `index.rst`, so we have to change how we add the metadata to the file.
This was referenced May 5, 2024
frankharkins
pushed a commit
to frankharkins/documentation
that referenced
this issue
Jul 22, 2024
Pulls in the fix for Qiskit#1272 to Runtime. Runtime now also calls its API index page `index.rst`, so we have to change how we add the metadata to the file.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Problem
Examples:
Note how the h1 is the module path, and then there is an h2 we wrote. That's the only h2: all other headers are h3.
The h2 comes from our docstring:
https://github.com/Qiskit/qiskit/blob/a41690d6075ac9438ff01b2346a35aa21dc3a568/qiskit/synthesis/unitary/aqc/__init__.py#L13-L23
Whereas the h1 comes from the autosummary template:
https://github.com/sphinx-doc/sphinx/blob/c41aab829d667a6fb5c9e6e8daf2d4b47b7ddebe/sphinx/ext/autosummary/templates/autosummary/module.rst?plain=1#L1-L3
We don't want that h1 to come from the autosummary template. Because of the way RST handles headings, setting the header in the template results in all subsequent headers being one heading level lower, like h1->h2. Instead, we should be treating the header in the docstring as the h1, which is how it works when we have manually defined module pages like
https://github.com/Qiskit/qiskit/blob/a41690d6075ac9438ff01b2346a35aa21dc3a568/docs/apidoc/circuit.rst?plain=1#L1-L6
This issue makes #942 worse.
attempted solutions so far
Sphinx crashes with both of these.
The text was updated successfully, but these errors were encountered: