Wrapped up the documentation for now

Author: Andrew J Westlake

README.md

@@ -5,32 +5,52 @@
 [![crates.io](http://meritbadge.herokuapp.com/pyo3-asyncio)](https://crates.io/crates/pyo3-asyncio)
 [![minimum rustc 1.45](https://img.shields.io/badge/rustc-1.45+-blue.svg)](https://rust-lang.github.io/rfcs/2495-min-rust-version.html)
 
-[Rust](http://www.rust-lang.org/) bindings for [Python](https://www.python.org/). This includes running and interacting with Python code from a Rust binary, as well as writing native Python modules.
+[Rust](http://www.rust-lang.org/) bindings for [Python](https://www.python.org/)'s [Asyncio Library](https://docs.python.org/3/library/asyncio.html). This crate facilitates interactions between Rust Futures and Python Coroutines and manages the lifecycle of their corresponding event loops.
 
 * API Documentation: [stable](https://docs.rs/pyo3-asyncio/) | [master](https://awestlake87.github.io/pyo3-asyncio/master/doc)
 
 * Contributing Notes: [github](https://github.com/awestlake87/pyo3-asyncio/blob/master/Contributing.md)
 
-## Overview
-
-This project contains an example of Python 3 asyncio and Tokio interop. It's
-designed to allow Python complete control over the main thread and facilitate
-interactions between rust and python coroutines.
-
-In addition, the `test` module contains a primitive test harness that will run
-a series of rust tests. We cannot use the default test harness because it would
-not allow Python to have control over the main thread. Instead we convert our
-test harness to an `asyncio.Future` and tell the Python `asyncio` event loop to
-drive the future to completion.
-
-Allowing Python to have control over the main thread also allows signals to work
-properly. CTRL-C will exit the event loop just as you would expect.
-
-Rust futures can be converted into python coroutines and vice versa. When a
-python coroutine raises an exception, the error should be propagated back with
-a `PyResult` as expected. Panics in Rust are translated into python Exceptions
-to propagate through the Python layers. This allows panics in tests to exit the
-event loop like before, but may cause unexpected behaviour if a Rust future
-awaits a Python coroutine that awaits a Rust future that panics.
-
-> These scenarios are currently untested in this crate.
+## Quickstart
+
+Here we initialize the runtime, import Python's `asyncio` library and run the given future to completion using Python's default `EventLoop` and Tokio. Inside the future, we convert `asyncio` sleep into a Rust future and await it.
+
+More details on the usage of this library can be found in the [API docs](https://awestlake87.github.io/pyo3-asyncio/master/doc).
+
+```rust no_run
+use pyo3::prelude::*;
+
+fn main() {
+    Python::with_gil(|py| {
+        // Initialize the runtime
+        pyo3_asyncio::with_runtime(py, || {
+            let asyncio: PyObject = py.import("asyncio")?.into();
+            
+            // Run the event loop until the given future completes
+            pyo3_asyncio::run_until_complete(py, async move {
+                Python::with_gil(|py| {
+                    // convert asyncio.sleep into a Rust Future
+                    pyo3_asyncio::into_future(
+                        py, 
+                        asyncio.call_method1(
+                            py, 
+                            "sleep", 
+                            (1.into_py(py),)
+                        )?
+                        .as_ref(py)
+                    )
+                })?
+                .await?;
+
+                Ok(())
+            })?;
+
+            Ok(())
+        })
+        .map_err(|e| {
+            e.print_and_set_sys_last_vars(py);  
+        })
+        .unwrap();
+    })
+}
+```

src/lib.rs

@@ -98,7 +98,7 @@ lazy_static! {
     };
 }
 
-const EXPECT_INIT: &'static str = "PyO3 Asyncio has not been initialized";
+const EXPECT_INIT: &str = "PyO3 Asyncio has not been initialized";
 
 static ASYNCIO: OnceCell<PyObject> = OnceCell::new();
 static EVENT_LOOP: OnceCell<PyObject> = OnceCell::new();

src/testing.rs

@@ -1,3 +1,83 @@
+//! # PyO3 Asyncio Testing Utilities
+//!
+//! This module provides some utilities for parsing test arguments as well as running and filtering
+//! a sequence of tests.
+//!
+//! As mentioned [here](crate#pythons-event-loop), PyO3 Asyncio tests cannot use the default test
+//! harness since it doesn't allow Python to gain control over the main thread. Instead, we have to
+//! provide our own test harness in order to create integration tests.
+//!
+//! ## Creating A PyO3 Asyncio Integration Test
+//!
+//! ### Main Test File
+//! First, we need to create the test's main file. Although these tests are considered integration
+//! tests, we cannot put them in the `tests` directory since that is a special directory owned by
+//! Cargo. Instead, we put our tests in a `pytests` directory, although the name `pytests` is just
+//! a convention.
+//!
+//! `pytests/test_example.rs`
+//! ```no_run
+//!
+//! fn main() {
+//!
+//! }
+//! ```
+//!
+//! ### Test Manifest Entry
+//! Next, we need to add our test file to the Cargo manifest. Add the following section to your
+//! `Cargo.toml`
+//!
+//! ```toml
+//! [[test]]
+//! name = "test_example"
+//! path = "pytests/test_example.rs"
+//! harness = false
+//! ```
+//!
+//! At this point you should be able to run the test via `cargo test`
+//!
+//! ### Using the PyO3 Asyncio Test Harness
+//! Now that we've got our test registered with `cargo test`, we can start using the PyO3 Asyncio
+//! test harness.
+//!
+//! In your `Cargo.toml` add the testing feature to `pyo3-asyncio`:
+//! ```toml
+//! pyo3-asyncio = { version = "0.13", features = ["testing"] }
+//! ```
+//!
+//! Now, in your test's main file, call [`testing::test_main`]:
+//!
+//! ```no_run
+//! fn main() {
+//!     pyo3_asyncio::testing::test_main(vec![]);
+//! }
+//! ```
+//!
+//! ### Adding Tests to the PyO3 Asyncio Test Harness
+//!
+//! ```no_run
+//! use pyo3_asyncio::testing::Test;
+//!
+//! fn main() {
+//!     pyo3_asyncio::testing::test_main(vec![
+//!         Test::new_async(
+//!             "test_async_sleep".into(),
+//!              async move {
+//!                  // async test body
+//!                 Ok(())
+//!              }
+//!         ),
+//!         Test::new_sync(
+//!             "test_blocking_sleep".into(),
+//!             || {
+//!                 // blocking test body
+//!                 Ok(())
+//!             }
+//!         ),
+//!     ]);
+//! }
+//! ```
+
 use std::{future::Future, pin::Pin};
 
 use clap::{App, Arg};
@@ -24,6 +104,34 @@ impl Default for Args {
 ///
 /// This should be called at the start of your test harness to give the CLI some
 /// control over how our tests are run.
+///
+/// Ideally, we should mirror the default test harness's arguments exactly, but
+/// for the sake of simplicity, only filtering is supported for now. If you want
+/// more features, feel free to request them
+/// [here](https://github.com/awestlake87/pyo3-asyncio/issues).
+///
+/// # Examples
+///
+/// Running the following function:
+/// ```no_run
+/// # use pyo3_asyncio::testing::parse_args;
+/// let args = parse_args("PyO3 Asyncio Example Test Suite");
+/// ```
+///
+/// Produces the following usage string:
+///
+/// ```bash
+/// Pyo3 Asyncio Example Test Suite
+/// USAGE:
+/// test_example [TESTNAME]
+///
+/// FLAGS:
+/// -h, --help       Prints help information
+/// -V, --version    Prints version information
+///
+/// ARGS:
+/// <TESTNAME>    If specified, only run tests containing this string in their names
+/// ```
 pub fn parse_args(suite_name: &str) -> Args {
     let matches = App::new(suite_name)
         .arg(