Improve README with a TOC, and other minor adjustments.

Sachaa-Thanasius · Sep 10, 2024 · 7b6af19 · 7b6af19
1 parent b3bccff
commit 7b6af19
Showing 1 changed file with 62 additions and 65 deletions.
diff --git a/README.rst b/README.rst
@@ -17,7 +17,8 @@ defer-imports
 
 A library that implements `PEP 690 <https://peps.python.org/pep-0690/>`_–esque lazy imports in pure Python, but at a user's behest within a context manager.
 
-.. contents:: Overview
+.. contents::
+    :local:
     :depth: 2
 
 
@@ -76,70 +77,66 @@ Use Cases
 -   If expensive imports are only necessary for certain code paths that won't always be taken, e.g. in subcommands in CLI tools.
 
 
-Extra: Console Usage
---------------------
-
-.. class:: details
-
-**Not relevant if you only plan to use ``defer-imports`` as a library.**
-    ``defer-imports`` works while within a regular Python REPL, as long as that work is being done in a package being imported and not with direct usage of the ``defer_imports.until_use`` context manager. To directly use the context manager, use the included interactive console:
-
-    -   From the command line::
-
-            > python -m defer_imports
-            Python 3.11.9 (tags/v3.11.9:de54cf5, Apr  2 2024, 10:12:12) [MSC v.1938 64 bit (AMD64)] on win32
-            Type "help", "copyright", "credits" or "license" for more information.
-            (DeferredInteractiveConsole)
-            >>> import defer_imports
-            >>> with defer_imports.until_use:
-            ...     import typing
-            ... 
-            >>> import sys           
-            >>> "typing" in sys.modules
-            False
-            >>> typing
-            <module 'typing' from 'C:\\Users\\Tusha\\AppData\\Local\\Programs\\Python\\Python311\\Lib\\typing.py'>
-            >>> "typing" in sys.modules
-            True
-
-    -   From within a standard Python interpreter:
-
-        .. code-block:: pycon
-
-            >>> from defer_imports import console
-            >>> console.interact()
-            Python 3.11.9 (tags/v3.11.9:de54cf5, Apr  2 2024, 10:12:12) [MSC v.1938 64 bit (AMD64)] on win32
-            Type "help", "copyright", "credits" or "license" for more information.
-            (DeferredInteractiveConsole)
-            >>> import defer_imports
-            >>> with defer_imports.until_use:
-            ...     import typing
-            ... 
-            >>> import sys           
-            >>> "typing" in sys.modules
-            False
-            >>> typing
-            <module 'typing' from 'C:\\Users\\Tusha\\AppData\\Local\\Programs\\Python\\Python311\\Lib\\typing.py'>
-            >>> "typing" in sys.modules
-            True
-
-
-    Additionally, if you're using IPython in a terminal or in a Jupyter environment, there is a function you can call to ensure the context manager works there as well:
-
-    .. code-block:: ipython
-
-        In [1]: from defer_imports import console
-        In [2]: console.instrument_ipython()
-        In [3]: import defer_imports
-        In [4]: with defer_imports.until_use:
-        ...:     import numpy
-        ...:
-        In [5]: import sys
-        In [6]: print("numpy" in sys.modules)
-        False
-        In [7]: numpy
-        In [8]: print("numpy" in sys.modules)
-        True
+Extra: Console
+--------------
+
+``defer-imports`` works while within a regular Python REPL, as long as that work is being done in a package being imported and not with direct usage of the ``defer_imports.until_use`` context manager. To directly use the context manager in a REPL, use the interactive console included within ``defer_imports.console``.
+
+You can start it from the command line::
+
+    > python -m defer_imports
+    Python 3.11.9 (tags/v3.11.9:de54cf5, Apr  2 2024, 10:12:12) [MSC v.1938 64 bit (AMD64)] on win32
+    Type "help", "copyright", "credits" or "license" for more information.
+    (DeferredInteractiveConsole)
+    >>> import defer_imports
+    >>> with defer_imports.until_use:
+    ...     import typing
+    ... 
+    >>> import sys           
+    >>> "typing" in sys.modules
+    False
+    >>> typing
+    <module 'typing' from 'C:\\Users\\...\\AppData\\Local\\Programs\\Python\\Python311\\Lib\\typing.py'>
+    >>> "typing" in sys.modules
+    True
+
+You can also start it while within a standard Python REPL:
+
+.. code-block:: pycon
+
+    >>> from defer_imports import console
+    >>> console.interact()
+    Python 3.11.9 (tags/v3.11.9:de54cf5, Apr  2 2024, 10:12:12) [MSC v.1938 64 bit (AMD64)] on win32
+    Type "help", "copyright", "credits" or "license" for more information.
+    (DeferredInteractiveConsole)
+    >>> import defer_imports
+    >>> with defer_imports.until_use:
+    ...     import typing
+    ... 
+    >>> import sys           
+    >>> "typing" in sys.modules
+    False
+    >>> typing
+    <module 'typing' from 'C:\\Users\\...\\AppData\\Local\\Programs\\Python\\Python311\\Lib\\typing.py'>
+    >>> "typing" in sys.modules
+    True
+
+Additionally, if you're using IPython in a terminal or Jupyter environment, there is a separate function you can call to ensure the context manager works there as well:
+
+.. code-block:: ipython
+
+    In [1]: from defer_imports import console
+    In [2]: console.instrument_ipython()
+    In [3]: import defer_imports
+    In [4]: with defer_imports.until_use:
+    ...:     import numpy
+    ...:
+    In [5]: import sys
+    In [6]: print("numpy" in sys.modules)
+    False
+    In [7]: numpy
+    In [8]: print("numpy" in sys.modules)
+    True
 
 
 Features