From 5264bb66076918601dc6c05b42b9a9711be544ce Mon Sep 17 00:00:00 2001
From: "mergify[bot]" <37929162+mergify[bot]@users.noreply.github.com>
Date: Fri, 1 Mar 2024 19:21:17 +0000
Subject: [PATCH] Improve header hierarchy for utils documentation (#11923)
 (#11932)

* Improve header hierarchy for utils documentation

* Fix pylint

* Review feedback

Co-authored-by: Jake Lishman <jake.lishman@ibm.com>

* Use mod cross-reference to self

---------

Co-authored-by: Jake Lishman <jake.lishman@ibm.com>
(cherry picked from commit 44e348a8479aac2f605129257ba37bd86e4b3b41)

Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
---
 qiskit/utils/__init__.py  | 24 ++++++++++++++++++------
 qiskit/utils/optionals.py |  6 +++---
 2 files changed, 21 insertions(+), 9 deletions(-)

diff --git a/qiskit/utils/__init__.py b/qiskit/utils/__init__.py
index d1cecf05d6b0..f5256f6f11ec 100644
--- a/qiskit/utils/__init__.py
+++ b/qiskit/utils/__init__.py
@@ -18,27 +18,39 @@
 
 .. 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 b72644885790..16a01a29d69e 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.  This module is a collection of objects that can
+Qiskit has several features that are enabled only if certain *optional* dependencies
+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.
 
@@ -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