Rules documentation improvements

README.md

@@ -18,3 +18,6 @@ Pairs well with flake8-bugbear.
 Some checks are incorporated into [ruff](https://github.com/astral-sh/ruff).
 
 This plugin was previously known as flake8-trio, and there was a separate small plugin known as flake8-async for asyncio. But this plugin was a superset of the checks in flake8-async, and support for anyio was added, so it's now named flake8-async to more properly convey its usage. At the same time all error codes were renamed from TRIOxxx to ASYNCxxx, as was previously used by the old flake8-async.
+
+## Rules
+https://flake8-async.readthedocs.io/en/latest/rules.html

docs/glossary.rst

@@ -0,0 +1,100 @@
+********
+Glossary
+********
+
+.. _cancel_scope:
+
+cancel scope
+------------
+A cancel scope is a context manager which can request the library cancels
+whatever task is executing in the body of the ``with`` (or ``async with``)
+block.  A cancel scope is the key component of a :ref:`timeout context <timeout_context>`, and used in :ref:`TaskGroups / Nurseries <taskgroup_nursery>` to cancel any remaining child tasks if one raises an
+exception.  Trio and AnyIO have an explicit ``CancelScope`` type; in asyncio
+they are implicit.
+
+* Trio
+
+  * `Documentation <https://trio.readthedocs.io/en/stable/reference-core.html#cancellation-and-timeouts>`__
+
+  * :class:`trio.CancelScope`
+
+* AnyIO
+
+  * `Documentation <https://anyio.readthedocs.io/en/stable/cancellation.html>`__
+
+  * :class:`anyio.CancelScope`
+
+.. _timeout_context:
+
+timeout context
+---------------
+A context manager that enforces a timeout on a block of code, by cancelling it
+after a specified duration or at a preset time.  The timeout can also be
+rescheduled after creation. They are internally implemented with a :ref:`cancel scope <cancel_scope>`, which in anyio & trio can be directly initialized with a deadline.
+
+.. I find this to have excessive spacing before/after sublists. Probably requires CSS to fix?
+
+* Trio
+
+  * `Documentation <https://trio.readthedocs.io/en/stable/reference-core.html#cancellation-and-timeouts>`__
+
+  * :func:`trio.move_on_after`, :func:`trio.move_on_at`, :func:`trio.fail_after`, :func:`trio.fail_at`, :class:`trio.CancelScope`
+
+* AnyIO
+
+  * `Documentation <https://anyio.readthedocs.io/en/stable/cancellation.html>`__
+
+  * :func:`anyio.move_on_after`, :func:`anyio.fail_after`, :class:`anyio.CancelScope`
+
+* asyncio
+
+  * `Documentation <https://docs.python.org/3/library/asyncio-task.html#timeouts>`__
+
+  * :func:`asyncio.timeout`, :func:`asyncio.timeout_at`
+
+.. _taskgroup_nursery:
+
+TaskGroup / Nursery
+-------------------
+
+A collection of child Tasks that can run concurrently. Internally contains a :ref:`cancel scope <cancel_scope>` for canceling any remaining child tasks if one raises an exception.
+
+* Trio
+
+  * `Documentation <https://trio.readthedocs.io/en/stable/reference-core.html#tasks-let-you-do-multiple-things-at-once>`__
+
+  * :class:`trio.Nursery`, created with :func:`trio.open_nursery`
+* AnyIO
+
+  * `Documentation <https://anyio.readthedocs.io/en/stable/tasks.html>`__
+  * :class:`anyio.abc.TaskGroup`, created with :func:`anyio.create_task_group`.
+* asyncio
+
+  * `Documentation <https://docs.python.org/3/library/asyncio-task.html#asyncio.TaskGroup>`__
+  * :class:`asyncio.TaskGroup` (since python 3.11)
+
+
+.. _cancelled:
+
+Cancelled / CancelledError
+--------------------------
+
+Handling cancellation is very sensitive, and you generally never want to catch a cancellation exception without letting it propagate to the library.
+
+  * Trio: :class:`trio.Cancelled`. `Documentation <https://trio.readthedocs.io/en/stable/reference-core.html#cancellation-and-timeouts>`__
+  * AnyIO: :func:`anyio.get_cancelled_exc_class`. `Documentation <https://anyio.readthedocs.io/en/stable/cancellation.html>`__
+  * asyncio: :class:`asyncio.CancelledError`. `Documentation <https://docs.python.org/3/library/asyncio-task.html#task-cancellation>`__
+
+.. _checkpoint:
+
+Checkpoint
+----------
+Checkpoints are ``await``, ``async for``, and ``async with`` (on one of enter/exit). TODO write more and link stuff
+
+.. _channel_stream_queue:
+
+Channel / Stream / Queue
+------------------------
+* Trio: `channel <https://trio.readthedocs.io/en/stable/reference-core.html#channels>`__
+* AnyIO: `stream <https://anyio.readthedocs.io/en/stable/streams.html#streams>`__
+* asyncio: `queue <https://docs.python.org/3/library/asyncio-queue.html>`__

docs/index.rst

@@ -8,7 +8,7 @@ flake8-async
 ############
 
 
-A highly opinionated flake8 plugin for problems related to `Trio <https://github.com/python-trio/trio>`_, `AnyIO <https://github.com/agronholm/anyio>`_, or `asyncio <https://docs.python.org/3/library/asyncio.html>`_.
+A highly opinionated flake8 plugin for problems related to `Trio <https://github.com/python-trio/trio>`__, `AnyIO <https://github.com/agronholm/anyio>`__, or `asyncio <https://docs.python.org/3/library/asyncio.html>`__.
 
 
 This can include anything from outright bugs, to pointless/dead code,
@@ -20,7 +20,7 @@ The plugin may well be too noisy or pedantic depending on your requirements or o
 Pairs well with flake8-bugbear.
 
 
-Some rules are incorporated into `ruff <https://docs.astral.sh/ruff/rules/#flake8-async-async>`_.
+Some rules are incorporated into `ruff <https://docs.astral.sh/ruff/rules/#flake8-async-async>`__.
 
 
 We previously maintained separate flake8-async and flake8-trio plugins, but merged both into this plugin under the more general "flake8-async" name after flake8-trio grew support for anyio and asyncio and became a superset of the former flake8-async.  All flake8-trio error codes were renamed from TRIOxxx to ASYNCxxx and the flake8-trio package is now deprecated.
@@ -33,6 +33,7 @@ Contents:
 
    usage
    rules
+   glossary
    changelog
    contributing
 
@@ -46,5 +47,6 @@ Indices and tables
 * :ref:`search`
 * :doc:`usage`
 * :doc:`rules`
+* :doc:`glossary`
 * :doc:`changelog`
 * :doc:`contributing`