tidy up some docs

Author: patrick-kidger

README.md

@@ -27,13 +27,13 @@ assert out == (4, 5)
 - An error in one coroutine will cancel all coroutines across the entire event loop.
     - If the erroring coroutine is sequentially depended on by a chain of other coroutines, then we chain their tracebacks for easier debugging.
     - Errors propagate to and from synchronous operations ran in threads.
-- Can nest tinyio loops inside each other, none of this one-per-thread business.
+- Can nest `tinyio` loops inside each other, none of this one-per-thread business.
 - Ludicrously simple. No need for futures, tasks, etc. Here's the entirety of the day-to-day API:
     ```python
     tinyio.Loop
-    tinyio.run_in_thread
-    tinyio.sleep
     tinyio.CancelledError
+    tinyio.sleep
+    tinyio.run_in_thread
     ```
 
 ## Installation

docs/error_propagation.md docs/api/error_propagation.mddocs/error_propagation.md renamed to docs/api/error_propagation.md

@@ -32,6 +32,22 @@ out = loop.run(foo())
 assert out == (4, 5)
 ```
 
+Somewhat unusually, our syntax uses `yield` rather than `await`, but the behaviour is the same. Await another coroutine with `yield coro`. Await on multiple with `yield [coro1, coro2, ...]` (a 'gather' in `asyncio` terminology; a 'nursery' in `trio` terminology).
+
+An error in one coroutine will cancel all coroutines across the entire event loop.
+
+- If the erroring coroutine is sequentially depended on by a chain of other coroutines, then we chain their tracebacks for easier debugging.
+- Errors propagate to and from synchronous operations ran in threads.
+
+Can nest `tinyio` loops inside each other, none of this one-per-thread business.
+
+Ludicrously simple. No need for futures, tasks, etc. Here's the entirety of the day-to-day API:
+
+- [`tinyio.Loop`][]
+- [`tinyio.CancelledError`][]
+- [`tinyio.sleep`][]
+- [`tinyio.run_in_thread`][]
+
 ## Next steps
 
 Check out the [coroutines and loops](./api/loops.md) page.

docs/index.md

@@ -90,14 +90,15 @@ plugins:
 
 nav:
     - 'index.md'
-    - 'error_propagation.md'
+    - 'api/loops.md'
+    - 'api/error_propagation.md'
     - API:
-        - 'api/loops.md'
         - 'api/sleeping.md'
         - 'api/threading.md'
         - 'api/synchronisation.md'
         - 'api/async_context_managers.md'
         - 'api/async_iterators.md'
         - 'api/integrations.md'
         - 'api/isolate.md'
-    - 'faq.md'
+    - Misc:
+        - 'faq.md'