Restructure and rewrite the docs for clarity

Signed-off-by: Sergey Vasilyev <nolar@nolar.info>

Author: nolar

docs/configuration.rst

@@ -88,7 +88,7 @@ The time zero
 ``start`` (``float`` or ``None``, or a no-argument callable that returns the same)
 is the initial time of the event loop.
 
-If it is a callable, it is invoked once per event loop to get the value:
+If it is a callable, it is invoked once per test to get the value:
 e.g., ``start=time.monotonic`` to align with the true time,
 or ``start=lambda: random.random() * 100`` to add some unpredictability.
 
@@ -134,3 +134,17 @@ e.g., ``end=lambda: time.monotonic() + 10``.
 
 The end of time is not the same as timeouts — see :doc:`nuances`
 on differences with ``async-timeout``.
+
+
+Advanced settings
+-----------------
+
+A few more settings are considered advanced and documented in :doc:`nuances`.
+They cover very nuanced aspects of the time flow, mainly synchronising across
+two timelines: fake time & real time, sync & async.
+You normally should not use them and the defaults should be fine.
+
+- ``noop_cycles``
+- ``idle_step``
+- ``idle_timeout``
+- ``resolution``

docs/introduction.rst

@@ -38,7 +38,7 @@ Why?
 
 Without ``looptime``, the event loops use ``time.monotonic()`` for the time,
 which also captures the code overhead and the network latencies, adding small
-random fluctuations to the time measurements (approx. 0.01-0.001 seconds).
+random fluctuations to the time measurements (approx. 0.1-0.01-0.001 seconds).
 
 Without ``looptime``, the event loops spend the real wall-clock time
 when there is no I/O happening but some callbacks are scheduled for later.

docs/nuances.rst

@@ -2,8 +2,8 @@
 Nuances
 =======
 
-Preliminary execution
-=====================
+Premature finalization
+======================
 
 Consider this test:
 
@@ -21,7 +21,7 @@ Consider this test:
             await asyncio.sleep(1)
 
 Normally, it should not fail. However, with fake time (without workarounds),
-the following scenario is possible:
+the following step-by-step scenario is possible:
 
 * ``async_timeout`` library sets its delayed timer at 9 seconds from now.
 * The event loop notices that there is only one timer at T0+9s.
@@ -36,13 +36,13 @@ tasks, and handles a fair chance to be entered, spawned, and scheduled.
 This is why the example works as intended.
 
 The ``noop_cycles`` (``int``) setting is how many cycles the event loop makes.
-The default is ``42``. Why 42? Well, …
+The default is ``42``. Why 42? Well, why not, indeed.
 
 
-Slow executors
-==============
+Sync-async synchronization
+==========================
 
-Consider this test:
+Consider this test, which mixes sync & async activities & primitives:
 
 .. code-block:: python
 
@@ -112,10 +112,10 @@ of steps with no fractions: e.g., 0.01 or 0.02 seconds in this example.
 A trade-off: a smaller step will get results faster but will spend more CPU power on resultless cycles.
 
 
-I/O idle
-========
+Idle I/O activities
+===================
 
-Consider this test:
+Consider this test, which does the external I/O communication:
 
 .. code-block:: python
 
@@ -145,7 +145,8 @@ The default is ``1.0`` second.
 
 If nothing happens within this time, the event loop assumes that nothing
 will ever happen, so it is a good idea to cease its existence: it injects
-``IdleTimeoutError`` (a subclass of ``asyncio.TimeoutError``) into all tasks.
+:class:`looptime.IdleTimeoutError` (a subclass of :class:`asyncio.TimeoutError`)
+into all currently running tasks.
 
 This is similar to how the end-of-time behaves, except that it is measured
 in the true-time timeline, while the end-of-time is in the fake-time timeline.
@@ -214,8 +215,8 @@ If the async timeout is reached, further code can proceed normally.
         assert chronometer < 0.1
 
 
-Time resolution
-===============
+Time resolution & floating point precision errors
+=================================================
 
 Python (as well as many other languages) has issues with calculating floats:
 
@@ -255,8 +256,8 @@ Normally, you should not worry about it or configure it.
     everything smaller than 0.001 becomes 0 and probably misbehaves.
 
 
-Time magic coverage
-===================
+Exclusion of fixture setup/teardown
+===================================
 
 The time compaction magic is enabled only for the duration of the test,
 i.e., the test function — but not the fixtures.
@@ -284,13 +285,33 @@ plus an assumption that it was never used by anyone (it should not be).
 It was rather a side effect of the previous implementation,
 which is not available or possible anymore.
 
+If the time magic is needed in fixtures, use the more explicit approach:
+
+.. code-block:: python
+
+    import looptime
+    import pytest_async
+
+    @pytest_async.fixture
+    def async_fixture_example():
+        with looptime.enabled():
+            # Execute some async time-based code, but compacted.
+            await asyncio.sleep(1)
+
+        # Go to the test(s).
+        yield
+
+        with looptime.enabled():
+            # Execute some async time-based code, but compacted.
+            await asyncio.sleep(1)
+
 
 pytest-asyncio>=1.0.0
 =====================
 
-As mentioned above, pytest-asyncio>=1.0.0 introduced several co-existing
-event loops of different scopes. Time compaction in these event loops
-is NOT activated. Only the running loop of the test function is activated.
+pytest-asyncio>=1.0.0 introduced several co-existing event loops
+of different scopes. Time compaction in these event loops is NOT activated.
+Only the running loop of the test function is activated.
 
 Configuring and activating multiple co-existing event loops brings a few
 conceptual challenges, which require a good sample case to look into

docs/tools.rst

@@ -8,7 +8,7 @@ Chronometers
 For convenience, the library also provides a class and a fixture
 to measure the duration of arbitrary code blocks in real-world time:
 
-* ``looptime.Chronometer`` (a context manager class).
+* :class:`looptime.Chronometer` (a context manager class).
 * ``chronometer`` (a pytest fixture).
 
 It can be used as a sync or async context manager:
@@ -71,8 +71,9 @@ beyond that precision is ignored — so you do not need to be afraid of
 ``123.456/1.2`` suddenly becoming ``102.88000000000001`` and not equal to ``102.88``
 (as long as the time proxy object is used and not converted to a native float).
 
-The proxy object can be used to create a new proxy that is bound to a specific
-event loop (it works for loops with both fake and real-world time):
+The proxy object can be used to create a new proxy that is bound
+to a specific event loop with the ``@`` operation
+(it works for loops with both fake and real-world time):
 
 .. code-block:: python
 
@@ -90,13 +91,13 @@ the loop time can start at a non-zero point; even if it starts at zero,
 the loop time also includes the time of all fixture setups.
 
 
-Custom event loops
-==================
+Custom event loops & mixins
+===========================
 
 Do you use a custom event loop? No problem! Create a test-specific descendant
 with the provided mixin — and it will work the same as the default event loop.
 
-For ``pytest-asyncio<1.0.0``:
+For ``pytest-asyncio<1.0.0``, use the ``event_loop`` fixture:
 
 .. code-block:: python
 
@@ -113,7 +114,7 @@ For ``pytest-asyncio<1.0.0``:
     def event_loop():
         return LooptimeCustomEventLoop()
 
-For ``pytest-asyncio>=1.0.0``:
+For ``pytest-asyncio>=1.0.0``, use the ``event_loop_policy``:
 
 .. code-block:: python
 
@@ -138,12 +139,13 @@ For ``pytest-asyncio>=1.0.0``:
 
 Only selector-based event loops are supported: the event loop must rely on
 ``self._selector.select(timeout)`` to sleep for ``timeout`` true-time seconds.
-Everything that inherits from ``asyncio.BaseEventLoop`` should work.
+Everything that inherits from ``asyncio.BaseEventLoop`` should work,
+but a more generic ``asyncio.AbstractEventLoop`` might be a problem.
 
 You can also patch almost any event loop class or event loop object
 the same way as ``looptime`` does (via some dirty hackery):
 
-For ``pytest-asyncio<1.0.0``:
+For ``pytest-asyncio<1.0.0`` and the ``even_loop`` fixture:
 
 .. code-block:: python
 
@@ -157,7 +159,7 @@ For ``pytest-asyncio<1.0.0``:
         loop = asyncio.new_event_loop()
         return looptime.patch_event_loop(loop)
 
-For ``pytest-asyncio>=1.0.0``:
+For ``pytest-asyncio>=1.0.0`` and the ``event_loop_policy`` fixture:
 
 .. code-block:: python
 
@@ -182,7 +184,9 @@ The resulting classes are cached, so it can be safely called multiple times.
 
 ``looptime.patch_event_loop()`` replaces the event loop's class with the newly
 constructed one. For those who care, it is an equivalent of the following hack
-(some restrictions apply to the derived class):
+(some restrictions apply to the derived class).
+
+In general, patching the existing event loop instance is done by this hack:
 
 .. code-block:: python
 

looptime/_internal/chronometers.py

@@ -14,13 +14,18 @@ class Chronometer(math.Numeric):
 
     Usage:
 
-        with Chronometer() as chronometer:
-            do_something()
-            print(f"Executing for {chronometer.seconds}s already.")
-            do_something_else()
+    .. code-block:: python
 
-        print(f"Executed in {chronometer.seconds}s.")
-        assert chronometer.seconds < 5.0
+        import time
+
+        def test_chronometer():
+            with Chronometer() as chronometer:
+                time.sleep(1.23)  # do something slow
+                print(f"Executing for {chronometer.seconds}s already.")
+                time.sleep(2.34)  # do something slow again
+
+            print(f"Executed in {chronometer.seconds}s.")
+            assert chronometer.seconds < 5.0  # 3.57s or slightly more
     """
 
     def __init__(self, clock: Callable[[], float] = time.perf_counter) -> None:
@@ -35,6 +40,7 @@ def _value(self) -> float:
 
     @property
     def seconds(self) -> float | None:
+        """The elapsed time in seconds (fractional)."""
         if self._ts is None:
             return None
         elif self._te is None:

looptime/_internal/loops.py

@@ -34,6 +34,9 @@ class IdleTimeoutError(asyncio.TimeoutError):
 
 
 class LoopTimeEventLoop(asyncio.BaseEventLoop):
+    """
+    An event loop with time compaction. Either a class or a mixin.
+    """
 
     # BaseEventLoop does not have "_selector" declared but uses it in _run_once().
     _selector: selectors.BaseSelector
@@ -134,12 +137,15 @@ def setup_looptime(
 
     @property
     def looptime_on(self) -> bool:
+        """
+        Whether the time compaction is enabled at the moment.
+        """
         return bool(self.__enabled)
 
     @contextlib.contextmanager
     def looptime_enabled(self) -> Iterator[None]:
         """
-        Temporarily enable the time compaction, restore the normal mode on exit.
+        A context manager to temporarily enable the time compaction.
         """
         if self.__enabled:
             raise RuntimeError('Looptime mode is already enabled. Entered twice? Avoid this!')

looptime/_internal/patchers.py

@@ -9,6 +9,12 @@
 
 
 def reset_caches() -> None:
+    """
+    Purge all caches populated by the patching function of ``looptime``.
+
+    The classes themselves are not destroyed, so if there are event loops
+    that were created before the caches are cleared, they will continue to work.
+    """
     _class_cache.clear()
 
 
@@ -17,6 +23,22 @@ def make_event_loop_class(
         *,
         prefix: str = 'Looptime',
 ) -> Type[loops.LoopTimeEventLoop]:
+    """
+    Create a new looptime-enabled event loop class from the original class.
+
+    Technically, it is equivalent to creating a new class that inherits
+    from the original class and :class:`looptime.LoopTimeEventLoop` as a mixin,
+    with no content (methods or fields) of its own:
+
+    .. code-block:: python
+
+        # Not the actual code, just the idea of what happens under the hood.
+        class NewEventLoop(loops.LoopTimeEventLoop, cls):
+            pass
+
+    New classes are cached, so the same original class always produces the same
+    derived class, not a new one on every call.
+    """
     if issubclass(cls, loops.LoopTimeEventLoop):
         return cls
     elif cls not in _class_cache:
@@ -29,6 +51,15 @@ def patch_event_loop(
         loop: asyncio.BaseEventLoop,
         **kwargs: Any,
 ) -> loops.LoopTimeEventLoop:
+    """
+    Patch an existing event loop to be looptime-ready.
+
+    This operation is idempotent and can be safely called multiple times.
+
+    Internally, it takes the existing class of the event loop and replaces it
+    with the new class, which is a mix of the original class and
+    :class:`looptime.LoopTimeEventLoop` as a mixin. The new classes are cached.
+    """
     result: loops.LoopTimeEventLoop
     match loop:
         case loops.LoopTimeEventLoop():
@@ -42,4 +73,7 @@ def patch_event_loop(
 
 
 def new_event_loop(**kwargs: Any) -> loops.LoopTimeEventLoop:
+    """
+    Create a new event loop as :func:`asyncio.new_event_loop`, but patched.
+    """
     return patch_event_loop(cast(asyncio.BaseEventLoop, asyncio.new_event_loop()), **kwargs)

looptime/_internal/timeproxies.py

@@ -8,6 +8,8 @@
 class LoopTimeProxy(math.Numeric):
     """
     A numeric-compatible proxy to the time of the current/specific event loop.
+
+    It is mainly represented by the ``looptime`` fixture in pytest.
     """
 
     def __init__(