Improve header hierarchy for utils documentation (Qiskit#11923)

* 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>

Author: 2 people

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
 """

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