Remove docs from README

Author: Patrick Kidger Bot

README.md

@@ -44,321 +44,12 @@ pip install tinyio
 
 ## Documentation
 
-### Loops
-
-Create a loop with `tinyio.Loop()`. It has a single method, `.run(coro)`, which consumes a coroutine, and which returns the output of that coroutine.
-
-Coroutines can `yield` four possible things:
-
-- `yield`: yield nothing, this just pauses and gives other coroutines a chance to run.
-- `yield coro`: wait on a single coroutine, in which case we'll resume with the output of that coroutine once it is available.
-- `yield [coro1, coro2, coro3]`: wait on multiple coroutines by putting them in a list, and resume with a list of outputs once all have completed. This is what `asyncio` calls a 'gather' or 'TaskGroup', and what `trio` calls a 'nursery'.
-- `yield {coro1, coro2, coro3}`: schedule one or more coroutines but do not wait on their result - they will run independently in the background.
-
-If you `yield` on the same coroutine multiple times (e.g. in a diamond dependency pattern) then the coroutine will be scheduled once, and on completion all dependees will receive its output. (You can even do this if the coroutine has already finished: `yield` on it to retrieve its output.)
-
-### Threading
-
-Blocking functions can be ran in threads using `tinyio.run_in_thread(fn, *args, **kwargs)`, which gives a coroutine you can `yield` on. Example:
-
-```python
-import time, tinyio
-
-def slow_blocking_add_one(x: int) -> int:
-    time.sleep(1)
-    return x + 1
-
-def foo(x: int):
-    out = yield [tinyio.run_in_thread(slow_blocking_add_one, x) for _ in range(3)]
-    return out
-
-loop = tinyio.Loop()
-out = loop.run(foo(x=1))  # runs in one second, not three
-assert out == [2, 2, 2]
-```
-
-### Sleeping
-
-This is `tinyio.sleep(delay_in_seconds)`, which is a coroutine you can `yield` on.
-
-### Error propagation
-
-If any coroutine raises an error, then:
-
-1. All coroutines across the entire loop will have `tinyio.CancelledError` raised in them (from whatever `yield` point they are currently waiting at).
-2. Any functions ran in threads via `tinyio.run_in_thread` will also have `tinyio.CancelledError` raised in the thread.
-3. The original error is raised out of `loop.run(...)`. This behaviour can be configured (e.g. to collect errors into a `BaseExceptionGroup`) by setting `loop.run(..., exception_group=None/False/True)`.
-
-This gives every coroutine a chance to shut down gracefully. Debuggers like [`patdb`](https://github.com/patrick-kidger/patdb) offer the ability to navigate across exceptions in an exception group, allowing you to inspect the state of all coroutines that were related to the error.
-
-## Further documentation
-
-<details><summary><h3>Synchronisation</h3> (Click to expand)</summary>
-
-We ship batteries-included with the usual collection of standard operations for synchronisation.
-
-```python
-tinyio.as_completed       tinyio.Semaphore
-tinyio.Barrier            tinyio.ThreadPool
-tinyio.Event              tinyio.timeout
-tinyio.Lock               tinyio.TimeoutError
-```
-
----
-
-- `tinyio.as_completed({coro1, coro2, ...})`
-
-    This schedules multiple coroutines in the background (like `yield {coro1, coro2, ...}`), and then offers their results in the order they complete.
-
-    This is iterated over in the following way, using its `.done()` and `.get()` methods:
-    ```python
-    def main():
-        iterator = yield tinyio.as_completed({coro1, coro2, coro3})
-        for next_coro in iterator:
-            result = yield next_coro
-    ```
-
----
-
-- `tinyio.Barrier(value)`
-
-    This has a single method `barrier.wait()`, which is a coroutine you can `yield` on. Once `value` many coroutines have yielded on this method then it will unblock.
-
----
-
-- `tinyio.Event()`
-
-    This is a wrapper around a boolean flag, initialised with `False`.
-    This has the following methods:
-    
-    - `.is_set()`: return the value of the flag.
-    - `.set()`: set the flag to `True`.
-    - `.clear()`: set the flag to `False`.
-    - `.wait(timeout_in_seconds=None)`, which is a coroutine you can `yield` on. This will unblock if the internal flag is `True` or if `timeout_in_seconds` seconds pass. (Typically the former is accomplished by calling `.set()` from another coroutine or from a thread.)
-
----
-
-- `tinyio.Lock()`
-
-    This is just a convenience for `tinyio.Semaphore(value=1)`, see below.
-
----
-
-- `tinyio.Semaphore(value)`
-
-    This manages an internal counter that is initialised at `value`, is decremented when entering a region, and incremented when exiting. This blocks if this counter is at zero. In this way, at most `value` coroutines may acquire the semaphore at a time.
-
-    This is used as:
-    ```python
-    semaphore = Semaphore(value)
-
-    ...
-
-    with (yield semaphore()):
-        ...
-    ```
-
----
-
-- `tinyio.timeout(coro, timeout_in_seconds)`
-
-    This is a coroutine you can `yield` on, used as `output, success = yield tinyio.timeout(coro, timeout_in_seconds)`.
-    
-    This runs `coro` for at most `timeout_in_seconds`. If it succeeds in that time then the pair `(output, True)` is returned . Else this will return `(None, False)`, and `coro` will be halted by raising `tinyio.TimeoutError` inside it.
-
----
-
-- `tinyio.ThreadPool(max_threads)`
-
-    This is equivalent to making multiple `tinyio.run_in_thread` calls, but will limit the number of threads to at most `max_threads`. Additional work after that will block until a thread becomes available.
-
-    This has two methods:
-
-    - `.run_in_thread(fn, *args, **kwargs)`, which is a coroutine you can `yield` on. This is equivalent to `yield tinyio.run_in_thread(fn, *args, **kwargs)`.
-    - `.map(fn, xs)`, which is a coroutine you can `yield` on. This is equivalent to `yield [tinyio.run_in_thread(fn, x) for x in xs]`.
- 
----
-
-</details>
-
-<details><summary><h3>Asynchronous context managers</h3> (Click to expand)</summary>
-
-You can use the following pattern to implement context managers with asynchronous entry:
-
-```python
-def my_coro():
-    with (yield my_context_manager(x=5)) as val:
-        print(f"Got val {val}")
-```
-where:
-```python
-def my_context_manager(x):
-    print("Initialising...")
-    yield tinyio.sleep(1)
-    print("Initialised")
-    return make_context_manager(x)
-
-@contextlib.contextmanager
-def make_context_manager(x):
-    try:
-        yield x
-    finally:
-        print("Cleaning up")
-```
-
-This isn't anything fancier than just using a coroutine that returns a regular `with`-compatible context manager. See `tinyio.Semaphore` for an example of this pattern.
-
-</details>
-
-<details><summary><h3>Asynchronous iterators</h3> (Click to expand)</summary>
-
-You can use the following pattern to implement asychronous iterators:
-
-```python
-def my_coro():
-    for x in slow_range(5):
-        x = yield x
-        print(f"Got {x}")
-```
-where:
-```python
-def slow_range(x):  # this function is an iterator-of-coroutines
-    for i in range(x):
-        yield slow_range_i(i)  # this `yield` statement is seen by the `for` loop
-
-def slow_range_i(i):  # this function is a coroutine
-    yield tinyio.sleep(1)  # this `yield` statement is seen by the `tinyio.Loop()`
-    return i
-```
-
-Here we just have `yield` being used in a couple of different ways that you're already used to:
-- as a regular Python generator/iterator;
-- as a `tinyio` coroutine.
-
-For an example of this, see `tinyio.as_completed`.
-
-</details>
-
-<details><summary><h3>Integration with `asyncio` and `trio`</h3> (Click to expand)</summary>
-
-We have support for putting `trio` event loops within `asyncio`/`trio` event loops, or vice-versa.
-
-```python
-tinyio.to_asyncio         tinyio.to_trio
-tinyio.from_asyncio       tinyio.from_trio
-```
-
----
-
-- `tinyio.to_asyncio(coro, exception_group=None)`
-
-    This converts a `tinyio` coroutine into an `asyncio` coroutine.
-
-    For example:
-    ```python
-    def add_one(x):
-        yield tinyio.sleep(1)
-        return x + 1
-
-    async def foo(x):
-        y = await tinyio.to_asyncio(add_one(x))
-        return y
-
-    asyncio.run(foo(3))
-    ```
-
----
-
-- `tinyio.from_asyncio(coro)`
-
-    This converts an `asyncio` coroutine into a `tinyio` coroutine.
-
-    > WARNING!  
-    > This works by running the entire `asyncio` portion in a separate thread. This may lead to surprises if the `asyncio` and non-`asyncio` portions interact in non-threadsafe ways.
-
-    For example:
-    ```python
-    async def add_one(x):
-        await asyncio.sleep(1)
-        return x + 1
-
-    def foo(x):
-        y = yield tinyio.from_asyncio(add_one(x))
-        return y
-
-    tinyio.Loop().run(foo(3))
-    ```
-
----
-
-- `tinyio.to_trio(coro, exception_group=None)`
-
-    This converts a `tinyio` coroutine into an `trio` coroutine.
-
-    For example:
-    ```python
-    def add_one(x):
-        yield tinyio.sleep(1)
-        return x + 1
-
-    async def foo(x):
-        y = await tinyio.to_trio(add_one(x))
-        return y
-
-    trio.run(foo, 3)
-    ```
-
----
-
-- `tinyio.from_trio(coro)`
-
-    This converts an `trio` coroutine into a `tinyio` coroutine.
-
-    For example:
-    ```python
-    async def add_one(x):
-        await trio.sleep(1)
-        return x + 1
-
-    def foo(x):
-        y = yield tinyio.from_trio(add_one(x))
-        return y
-
-    tinyio.Loop().run(foo(3))
-    ```
-
----
-
-</details>
-
-<details><summary><h3>Isolating some coroutines without crashing the others</h3> (Click to expand)</summary>
-
-If you would like to run a coroutine (and transitively, all the coroutines it `yield`s) without crashing the entire event loop, then you can use `tinyio.isolate`. This will run the coroutine in a nested `tinyio.Loop` – so that it crashing will only affect everything in that nested loop – and then return the result or the error.
-
-```python
-def some_coroutine(x):
-    if x == 3:
-        raise ValueError("Oh no, a bug!")
-    yield
-
-def someone_elses_buggy_code():
-    yield [some_coroutine(x=3), another_coroutine()]
-
-def main():
-    app = someone_elses_buggy_code()
-    result_or_error, success = yield tinyio.isolate(app)
-    # at this point then `someone_elses_buggy_code`, `some_coroutine` and
-    #`another_coroutine` have been cancelled, but `main` is still running.
-```
-
-</details>
+Available at [https://docs.kidger.site/tinyio](https://docs.kidger.site/tinyio).
 
 ## FAQ
 
-(Click to expand)
-
 <details>
-<summary>Why <code>yield</code> - why not <code>await</code> like is normally seen for coroutines?</summary>
+<summary>Why <code>yield</code> — why not <code>await</code> like is normally seen for coroutines?</summary>
 <br>
 
 The reason is that `await` does not offer a suspension point to an event loop (it just calls `__await__` and maybe *that* offers a suspension point), so if we wanted to use that syntax then we'd need to replace `yield coro` with something like `await tinyio.Task(coro)`. The traditional syntax is not worth the extra class.