Improve function handling (Qiskit#683)

This PR improves how the API generation script handles functions.

## Changes

### Demote some `h2` tags to `strong`

We currently convert all `.rubric` elements to `h2`, but this makes some
headings higher-level than they should be (specifically "Example" and
"References" headings). For an example see
[api/qiskit/converters](https://docs.quantum.ibm.com/api/qiskit/converters).

<img width="197" alt="Screenshot 2024-01-23 at 17 37 33"
src="https://github.com/Qiskit/documentation/assets/36071638/618a256b-9bdf-481b-bb49-e3eea7476b8e">

This PR converts rubrics to `strong` (rather than `h2`) if the name is
"Example(s)" or "Reference(s)". This is a bit hacky, but it seems to
work and I can't think of a better way of doing it. The Sphinx LaTeX
writer also takes a [similar
approach](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-rubric).

I've regenerated the docs using this new logic and I can see no false
positives (that is, cases in which we use `strong` where we should use
`h2`).


### Add function names as headings

Functions currently have no headings. This PR adds a `h3` with the
function name, which improves readability, gives anchor tag icons, and
will add more functions to the right sidebar.

I've also included some logic to avoid adding function names when the
page is already dedicated to the function (such as
[least_busy](https://docs.quantum.ibm.com/api/qiskit-ibm-provider/qiskit_ibm_provider.least_busy)).

One quirk with this I spotted was some function names not appearing in
the sidebar in `/api/qiskit/utils` (see `add_deprecation_to_docstring`
in the screenshot). This is possibly because the title hierarchy skips
`h2`.

![Screenshot 2024-01-23 at 18 00
37](https://github.com/Qiskit/documentation/assets/36071638/c189dfc1-3535-4e2e-9edb-889ba855ef10)

***

Closes Qiskit#231

---------

Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>

docs/api/qiskit-ibm-provider/qiskit_ibm_provider.visualization.iplot_error_map.md

@@ -38,7 +38,7 @@ The error map figure.
 *   **VisualizationValueError** – If an invalid input is received.
 *   **VisualizationTypeError** – If the specified backend is a simulator.
 
-## Example
+**Example**
 
 ```python
 from qiskit_ibm_provider import IBMProvider

docs/api/qiskit-ibm-provider/qiskit_ibm_provider.visualization.iplot_gate_map.md

@@ -39,7 +39,7 @@ Plots an interactive gate map of a device.
 
 The gate map figure.
 
-## Example
+**Example**
 
 ```python
 from qiskit_ibm_provider import IBMProvider

docs/api/qiskit/algorithms.md

@@ -213,6 +213,8 @@ Utility classes used by algorithms (mainly for type-hinting purposes).
 
 Utility functions used by algorithms.
 
+### eval\_observables
+
 <span id="qiskit.algorithms.eval_observables" />
 
 `qiskit.algorithms.eval_observables(quantum_instance, quantum_state, observables, expectation, threshold=1e-12)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.45/qiskit/algorithms/aux_ops_evaluator.py "view source code")
@@ -245,6 +247,8 @@ A list or a dictionary of tuples (mean, standard deviation).
 
 ListOrDict\[[tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")\[[complex](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)"), [complex](https://docs.python.org/3/library/functions.html#complex "(in Python v3.12)")]]
 
+### estimate\_observables
+
 <span id="qiskit.algorithms.estimate_observables" />
 
 `qiskit.algorithms.estimate_observables(estimator, quantum_state, observables, parameter_values=None, threshold=1e-12)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.45/qiskit/algorithms/observables_evaluator.py "view source code")

docs/api/qiskit/assembler.md

@@ -20,6 +20,8 @@ python_api_name: qiskit.assembler
 
 ## Circuit Assembler
 
+### assemble\_circuits
+
 <span id="qiskit.assembler.assemble_circuits" />
 
 `qiskit.assembler.assemble_circuits(circuits, run_config, qobj_id, qobj_header)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.45/qiskit/assembler/assemble_circuits.py "view source code")
@@ -41,7 +43,7 @@ The qobj to be run on the backends
 
 [*QasmQobj*](qiskit.qobj.QasmQobj "qiskit.qobj.qasm_qobj.QasmQobj")
 
-## Examples
+**Examples**
 
 ```python
 from qiskit.circuit import QuantumRegister, ClassicalRegister, QuantumCircuit
@@ -63,6 +65,8 @@ qobj = assemble_circuits(circuits=[qc],
 
 ## Schedule Assembler
 
+### assemble\_schedules
+
 <span id="qiskit.assembler.assemble_schedules" />
 
 `qiskit.assembler.assemble_schedules(schedules, qobj_id, qobj_header, run_config)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.45/qiskit/assembler/assemble_schedules.py "view source code")
@@ -88,7 +92,7 @@ The Qobj to be run on the backends.
 
 [*PulseQobj*](qiskit.qobj.PulseQobj "qiskit.qobj.pulse_qobj.PulseQobj")
 
-## Examples
+**Examples**
 
 ```python
 from qiskit import pulse
@@ -127,6 +131,8 @@ pulseQobj = assemble_schedules(schedules=[schedule],
 
 ## Disassembler
 
+### disassemble
+
 <span id="qiskit.assembler.disassemble" />
 
 `qiskit.assembler.disassemble(qobj)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.45/qiskit/assembler/disassemble.py "view source code")
@@ -153,7 +159,7 @@ The disassembled program which consists of:
 
 Union\[CircuitModule, PulseModule]
 
-## Examples
+**Examples**
 
 ```python
 from qiskit.circuit import QuantumRegister, ClassicalRegister, QuantumCircuit

docs/api/qiskit/circuit.md

@@ -284,6 +284,8 @@ with qc.switch(cr) as case:
 
 ### Random Circuits
 
+### random\_circuit
+
 <span id="qiskit.circuit.random.random_circuit" />
 
 `qiskit.circuit.random.random_circuit(num_qubits, depth, max_operands=4, measure=False, conditional=False, reset=False, seed=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.45/qiskit/circuit/random/utils.py "view source code")