Repository: Qiskit/qiskit

Issue:
State Visualizations have inconsistent return types in the docs
### Environment

- **Qiskit Terra version**: 

Current versions of docs as of 2pm ET on June 26, 2023
https://qiskit.org/documentation/apidoc/visualization.html#state-visualizations
https://github.com/Qiskit/qiskit-terra/blob/791a45433a21a5604086bfcd96d804433b8aecfe/qiskit/visualization/state_visualization.py

### What is happening?

All state visualizations return a matplotlib.Figure. However, some docstrings report this as a `Figure`, some as a `matplotlib.Figure`. 

ex: https://qiskit.org/documentation/stubs/qiskit.visualization.plot_bloch_vector.html#qiskit.visualization.plot_bloch_vector
ex: https://qiskit.org/documentation/stubs/qiskit.visualization.plot_state_hinton.html#qiskit.visualization.plot_state_hinton

The inconsistency is a bit confusing (for example, a user might wonder if there's a difference between a Figure and matplotlib.Figure).

### How can we reproduce the issue?

Check the docs:

https://qiskit.org/documentation/apidoc/visualization.html#state-visualizations

https://github.com/Qiskit/qiskit-terra/blob/791a45433a21a5604086bfcd96d804433b8aecfe/qiskit/visualization/state_visualization.py

### What should happen?

Ideally, all would list a common return type.



### Any suggestions?

I'm happy to submit a PR to update all return types to `matplotlib.Figure` if that's the agreed-upon solution.


Discussion:
Thanks for the report.  The actual ideal return value would be something that `intersphinx` can resolve into a link to [`matplotlib.figure.Figure`](https://matplotlib.org/stable/api/figure_api.html#matplotlib.figure.Figure).  I don't know off the top of my head how easy Sphinx will make that, especially if there are any instances where we're using `autodoc`'s automated processing of type hints to produce the Sphinx `rtype` directive, but it would be a welcome PR to make that cross-referencing work correctly.
Ok -- I'll dig into it and open a PR once I've got the cross-referencing to the matplotlib doc working.

Resolving patch:
diff --git a/docs/conf.py b/docs/conf.py
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -69,6 +69,7 @@
     "qiskit-ibm-runtime": ("https://qiskit.org/ecosystem/ibm-runtime/", None),
     "qiskit-aer": ("https://qiskit.org/ecosystem/aer/", None),
     "numpy": ("https://numpy.org/doc/stable/", None),
+    "matplotlib": ("https://matplotlib.org/stable/", None),
 }
 
 # -- Options for HTML output -------------------------------------------------
diff --git a/qiskit/visualization/state_visualization.py b/qiskit/visualization/state_visualization.py
--- a/qiskit/visualization/state_visualization.py
+++ b/qiskit/visualization/state_visualization.py
@@ -66,7 +66,7 @@ def plot_state_hinton(
             it is redundant.
 
     Returns:
-         matplotlib.Figure:
+        :class:`matplotlib:matplotlib.figure.Figure` :
             The matplotlib.Figure of the visualization if
             neither ax_real or ax_imag is set.
 
@@ -209,7 +209,7 @@ def plot_bloch_vector(
         font_size (float): Font size.
 
     Returns:
-        Figure: A matplotlib figure instance if ``ax = None``.
+        :class:`matplotlib:matplotlib.figure.Figure` : A matplotlib figure instance if ``ax = None``.
 
     Raises:
         MissingOptionalLibraryError: Requires matplotlib.
@@ -285,7 +285,7 @@ def plot_bloch_multivector(
         title_pad (float): Padding for the title (suptitle `y` position is `y=1+title_pad/100`).
 
     Returns:
-        matplotlib.Figure:
+        :class:`matplotlib:matplotlib.figure.Figure` :
             A matplotlib figure instance.
 
     Raises:
@@ -401,7 +401,7 @@ def plot_state_city(
             it is redundant.
 
     Returns:
-         matplotlib.Figure:
+        :class:`matplotlib:matplotlib.figure.Figure` :
             The matplotlib.Figure of the visualization if the
             ``ax_real`` and ``ax_imag`` kwargs are not set
 
@@ -643,7 +643,7 @@ def plot_state_paulivec(
             will be no returned Figure since it is redundant.
 
     Returns:
-         matplotlib.Figure:
+         :class:`matplotlib:matplotlib.figure.Figure` :
             The matplotlib.Figure of the visualization if the
             ``ax`` kwarg is not set
 
@@ -823,7 +823,8 @@ def plot_state_qsphere(
             radians or degrees for the phase values in the plot.
 
     Returns:
-        Figure: A matplotlib figure instance if the ``ax`` kwarg is not set
+        :class:`matplotlib:matplotlib.figure.Figure` :
+            A matplotlib figure instance if the ``ax`` kwarg is not set
 
     Raises:
         MissingOptionalLibraryError: Requires matplotlib.


Test patch: