From 0df0d06cbebf11e37c0c8eaa3fcdfd600391bb36 Mon Sep 17 00:00:00 2001
From: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
Date: Thu, 29 Feb 2024 08:33:53 -0500
Subject: [PATCH 1/4] Improve header hierarchy for utils documentation

---
 qiskit/utils/__init__.py  | 23 +++++++++++++++++++----
 qiskit/utils/optionals.py |  4 ++--
 2 files changed, 21 insertions(+), 6 deletions(-)

diff --git a/qiskit/utils/__init__.py b/qiskit/utils/__init__.py
index d1cecf05d6b..41754c10398 100644
--- a/qiskit/utils/__init__.py
+++ b/qiskit/utils/__init__.py
@@ -18,27 +18,42 @@
 
 .. currentmodule:: qiskit.utils
 
+Deprecations
+------------
+
 .. autofunction:: add_deprecation_to_docstring
 .. autofunction:: deprecate_arg
 .. autofunction:: deprecate_arguments
 .. autofunction:: deprecate_func
 .. autofunction:: deprecate_function
-.. autofunction:: local_hardware_info
-.. autofunction:: is_main_process
+
+SI unit conversion
+------------------
+
 .. autofunction:: apply_prefix
 .. autofunction:: detach_prefix
+
+Class tools
+-----------
+
 .. autofunction:: wrap_method
 
+Multiprocessing
+---------------
+
+.. autofunction:: local_hardware_info
+.. autofunction:: is_main_process
 
 Parallel Routines
 -----------------
+
 A helper function for calling a custom function with python
 :class:`~concurrent.futures.ProcessPoolExecutor`. Tasks can be executed in parallel using this function.
 
 .. autofunction:: parallel_map
 
-Optional Dependency Checkers (:mod:`qiskit.utils.optionals`)
-============================================================
+Optional Dependency Checkers
+----------------------------
 
 .. automodule:: qiskit.utils.optionals
 """
diff --git a/qiskit/utils/optionals.py b/qiskit/utils/optionals.py
index b7264488579..0bdb050b60f 100644
--- a/qiskit/utils/optionals.py
+++ b/qiskit/utils/optionals.py
@@ -14,7 +14,7 @@
 .. currentmodule:: qiskit.utils.optionals
 
 Qiskit has several features that are enabled only
-if certain *optional* dependencies are satisfied.  This module is a collection of objects that can
+if certain *optional* dependencies are satisfied.  The ``qiskit.utils.optionals`` module has a collection of objects that can
 be used to test if certain functionality is available, and optionally raise
 :class:`.MissingOptionalLibraryError` if the functionality is not available.
 
@@ -52,7 +52,7 @@
     :widths: 25 75
 
     * - .. py:data:: HAS_CONSTRAINT
-      - `python-constraint <https://github.com/python-constraint/python-constraint>__ is a
+      - `python-constraint <https://github.com/python-constraint/python-constraint>`__ is a
         constraint satisfaction problem solver, used in the :class:`~.CSPLayout` transpiler pass.
 
     * - .. py:data:: HAS_CPLEX

From 023069dfc6e1eee8fee9365a684c6088ad76e148 Mon Sep 17 00:00:00 2001
From: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
Date: Thu, 29 Feb 2024 11:40:26 -0500
Subject: [PATCH 2/4] Fix pylint

---
 qiskit/utils/optionals.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/qiskit/utils/optionals.py b/qiskit/utils/optionals.py
index 0bdb050b60f..798b2192425 100644
--- a/qiskit/utils/optionals.py
+++ b/qiskit/utils/optionals.py
@@ -13,8 +13,8 @@
 """
 .. currentmodule:: qiskit.utils.optionals
 
-Qiskit has several features that are enabled only
-if certain *optional* dependencies are satisfied.  The ``qiskit.utils.optionals`` module has a collection of objects that can
+Qiskit has several features that are enabled only if certain *optional* dependencies
+are satisfied. The ``qiskit.utils.optionals`` module has a collection of objects that can
 be used to test if certain functionality is available, and optionally raise
 :class:`.MissingOptionalLibraryError` if the functionality is not available.
 

From 608d33cfdea706b43b923f4b995dba1eceda75cc Mon Sep 17 00:00:00 2001
From: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
Date: Thu, 29 Feb 2024 12:50:27 -0500
Subject: [PATCH 3/4] Review feedback

Co-authored-by: Jake Lishman <jake.lishman@ibm.com>
---
 qiskit/utils/__init__.py  | 13 +++++--------
 qiskit/utils/optionals.py |  2 +-
 2 files changed, 6 insertions(+), 9 deletions(-)

diff --git a/qiskit/utils/__init__.py b/qiskit/utils/__init__.py
index 41754c10398..f5256f6f11e 100644
--- a/qiskit/utils/__init__.py
+++ b/qiskit/utils/__init__.py
@@ -19,7 +19,7 @@
 .. currentmodule:: qiskit.utils
 
 Deprecations
-------------
+============
 
 .. autofunction:: add_deprecation_to_docstring
 .. autofunction:: deprecate_arg
@@ -28,32 +28,29 @@
 .. autofunction:: deprecate_function
 
 SI unit conversion
-------------------
+==================
 
 .. autofunction:: apply_prefix
 .. autofunction:: detach_prefix
 
 Class tools
------------
+===========
 
 .. autofunction:: wrap_method
 
 Multiprocessing
----------------
+===============
 
 .. autofunction:: local_hardware_info
 .. autofunction:: is_main_process
 
-Parallel Routines
------------------
-
 A helper function for calling a custom function with python
 :class:`~concurrent.futures.ProcessPoolExecutor`. Tasks can be executed in parallel using this function.
 
 .. autofunction:: parallel_map
 
 Optional Dependency Checkers
-----------------------------
+============================
 
 .. automodule:: qiskit.utils.optionals
 """
diff --git a/qiskit/utils/optionals.py b/qiskit/utils/optionals.py
index 798b2192425..b12626ed216 100644
--- a/qiskit/utils/optionals.py
+++ b/qiskit/utils/optionals.py
@@ -14,7 +14,7 @@
 .. currentmodule:: qiskit.utils.optionals
 
 Qiskit has several features that are enabled only if certain *optional* dependencies
-are satisfied. The ``qiskit.utils.optionals`` module has a collection of objects that can
+are satisfied. This module, ``qiskit.utils.optionals``, has a collection of objects that can
 be used to test if certain functionality is available, and optionally raise
 :class:`.MissingOptionalLibraryError` if the functionality is not available.
 

From e530b3140691a2690f9e4cd163865147f87fa606 Mon Sep 17 00:00:00 2001
From: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
Date: Thu, 29 Feb 2024 15:17:33 -0500
Subject: [PATCH 4/4] Use mod cross-reference to self

---
 qiskit/utils/optionals.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/qiskit/utils/optionals.py b/qiskit/utils/optionals.py
index b12626ed216..16a01a29d69 100644
--- a/qiskit/utils/optionals.py
+++ b/qiskit/utils/optionals.py
@@ -14,7 +14,7 @@
 .. currentmodule:: qiskit.utils.optionals
 
 Qiskit has several features that are enabled only if certain *optional* dependencies
-are satisfied. This module, ``qiskit.utils.optionals``, has a collection of objects that can
+are satisfied. This module, :mod:`qiskit.utils.optionals`, has a collection of objects that can
 be used to test if certain functionality is available, and optionally raise
 :class:`.MissingOptionalLibraryError` if the functionality is not available.