Some functions and exceptions don't show up in the right sidebar

[Eric-Arellano]

Thanks to #713 and #683, we now add headers at level 3, whereas before we didn't add headers. This is a big UX improvement because in most cases, the headers show up in the right side bar; it also allows users to get an anchor link to the code object.

However, h3 is not always the right choice; it depends on the heading level of the surrounding context. For example:

• /api/qiskit/circuit#circuiterror should be h4
• All exceptions in /api/qiskit/exceptions should be h2

Some of the functions in api/qiskit/utils should be h2, whereas some should remain h3.

This issues causes certain code objects to not show up in the right sidebar.

Example: utils module

an h2:

an h3:

Alternative: change right side bar behavior

Visual design wise, is it okay for some functions/exceptions to be h2?

The alternative would be to change the right sidebar so that h3 shows up even if there isn't a parent h2. That way we're consistent with how functions look.

Alternative: change the content itself to always have h2 headers

For example, in utils, add a section like ## General utility functions

[javabster]

After discussion with design we think this is the best option moving forward:

[Eric-Arellano]

Fixed by Eric Harvey in closed source. Thanks!