Move API headers inside the component

[Eric-Arellano]

This is similar in spirit to https://github.com/Qiskit/documentation/issues/948. There, we were proposing getting rid of the header entirely, and we decided to not do it for a few reasons:

1. We like the visual design of having the header
2. Our search differentiates between headers vs body, and we want to keep the header as a search entry
3. The header should show up in the right page ToC (if it's the correct level w/ module pages)
4. The header makes the anchor link experience consistent with the rest of the platform and simpler to implement, such as avoiding issues with overloaded signatures (semi-related to https://github.com/Qiskit/qiskit_sphinx_theme/pull/458)

Unlike #948, this is not proposing removing headers entirely. Instead, it proposes moving the header inside the code component, and replacing the <h3>-<h6> element with <dl>, <dt>, and <dd> for better HTML semantics.

Before:

After (proof-of-concept):

Motivation

We noticed in https://github.com/Qiskit/qiskit/pull/12403#pullrequestreview-2058568298 that the header living above the code object and its margin-top is resulting in unclear API docs where it is not clear which text describes the code object.

This proposal is meant to make the code component more self-contained, that the entire definition is in one place and contained by the left colored bar.

@jakelishman is also correct in https://github.com/Qiskit/qiskit/pull/12403#issuecomment-2113278154 that the HTML semantics would be more appropriate to use <dl>, <dt>, and <dd> rather than <h3> because indeed these code components are giving a single self-contained definition, rather than defining a new heading section that applies to all content beneath it. Improving the HTML modeling better complies with semantic web, which helps accessibility and SEO. (Note that we can still style <dl> however we want!)

Implementation

Styling & levels

We will style the <dt> similar to <h3> - <h6>, although it should have less margin-top.

TBD if the <dt> should render differently based on the surrounding headers. For example, https://docs.quantum.ibm.com/api/qiskit/dev/circuit#bits-and-registers is an h3; should the <dt> look like an <h4> or <h3>?

Option 1: h4

Option 2: h3

For inline classes, what about their methods? Should they still look like a smaller header than their owning class?

example of inline class using h4 and h5

Note that the level we use for styling does not need to be the same as the level we use for the Page ToC! That is unlike the current implementation. This is more flexible.

(Eric's thoughts: we should preserve the current behavior of headers getting smaller based on surrounding context. It visually shows the information hierarchy better. For example, if you have a <Function> inside an h5 section, it is visually confusing to show the Function's header as h3.)

Page ToC

The Page ToC code will need to be modified to read the <dt> from these components. We'll need to know the "level" because we only show h1-h3 on class pages and h2-h3 on module pages, so we should not show any <dt> where the level >3.

Search

We need to teach the search index script (parseDocument.ts) to treat these <dt>s as headers. We should probably always treat <dt> as a header for search - note that we don't ever use <dt> atm.

Anchor tag

We need to preserve this mechanism

[jakelishman]

Thank you so much for this! I know it's probably not the biggest priority, but it'll be great to have it.

[javabster]

This change looks sensible to me - as for styling I dont really have strong feelings between option 1 or 2, maybe option 2 is slightly nicer?