Skip to content
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

Closed
Tracked by #479
Eric-Arellano opened this issue May 1, 2024 · 0 comments · Fixed by Qiskit/qiskit#12331
Closed
Tracked by #479

Comments

@Eric-Arellano
Copy link
Collaborator

Eric-Arellano commented May 1, 2024

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.

Screenshot 2024-05-01 at 1 10 49 PM Screenshot 2024-05-01 at 1 11 21 PM

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

  • Remove the h1 from the module docstring so that we only have its h2s (multiple of them).
  • Override the module template to not add the h1.

Sphinx crashes with both of these.

@Eric-Arellano Eric-Arellano self-assigned this May 1, 2024
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.
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.
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.
@javabster javabster removed this from Docs Planning Feb 5, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging a pull request may close this issue.

1 participant