Proofread docs and set up RTD (#57)

* Published to RTD.
* Proofread the previous commit.
* Added sphinxcontrib-trio so that async APIs are documented correctly.
* Added credits page.

Author: mehaase

README.md

@@ -1,10 +1,3 @@
-[![PyPI](https://img.shields.io/pypi/v/trio-websocket.svg?style=flat-square)](https://pypi.org/project/trio-websocket/)
-![Python Versions](https://img.shields.io/pypi/pyversions/trio-websocket.svg?style=flat-square)
-![MIT License](https://img.shields.io/github/license/HyperionGray/trio-websocket.svg?style=flat-square)
-[![Build Status](https://img.shields.io/travis/HyperionGray/trio-websocket.svg?style=flat-square)](https://travis-ci.org/HyperionGray/trio-websocket)
-[![Coverage](https://img.shields.io/coveralls/github/HyperionGray/trio-websocket.svg?style=flat-square)](https://coveralls.io/github/HyperionGray/trio-websocket?branch=master)
-![Read the Docs](https://img.shields.io/readthedocs/trio-websocket.svg)
-
 # Trio WebSocket
 
 This library implements [the WebSocket
@@ -20,6 +13,13 @@ framework](https://trio.readthedocs.io/en/latest/). This library passes the
 This README contains a brief introduction to the project. Full documentation [is
 available here](https://trio-websocket.readthedocs.io).
 
+[![PyPI](https://img.shields.io/pypi/v/trio-websocket.svg?style=flat-square)](https://pypi.org/project/trio-websocket/)
+![Python Versions](https://img.shields.io/pypi/pyversions/trio-websocket.svg?style=flat-square)
+![MIT License](https://img.shields.io/github/license/HyperionGray/trio-websocket.svg?style=flat-square)
+[![Build Status](https://img.shields.io/travis/HyperionGray/trio-websocket.svg?style=flat-square)](https://travis-ci.org/HyperionGray/trio-websocket)
+[![Coverage](https://img.shields.io/coveralls/github/HyperionGray/trio-websocket.svg?style=flat-square)](https://coveralls.io/github/HyperionGray/trio-websocket?branch=master)
+[![Read the Docs](https://img.shields.io/readthedocs/trio-websocket.svg)](https://trio-websocket.readthedocs.io)
+
 ## Installation
 
 This library requires Python 3.5 or greater. To install from PyPI:

docs/api.rst

@@ -37,10 +37,9 @@ Connections
         The preferred way to obtain a connection is to use one of the
         convenience functions described in :ref:`websocket-clients` or
         :ref:`websocket-servers`. Instantiating a connection instance directly is
-        tricky and only advisable for esoteric use cases.
+        tricky and is not recommended.
 
-    A connection has properties that expose the connection's role (client vs.
-    server) and other connection metadata.
+    This object has properties that expose connection metadata.
 
     .. autoattribute:: is_closed
     .. autoattribute:: close_reason
@@ -68,7 +67,7 @@ Connections
     .. automethod:: pong
 
     Finally, the socket offers a method to close the connection. The connection
-    context managers in ref:`websocket-clients` and :ref:`websocket-servers`
+    context managers in :ref:`websocket-clients` and :ref:`websocket-servers`
     will automatically close the connection for you, but you may want to close
     the connection explicity if you are not using a context manager or if you
     want to customize the close reason.
@@ -79,4 +78,3 @@ Connections
     :members:
 
 .. autoexception:: ConnectionClosed
-    :members:

docs/clients.rst

@@ -5,11 +5,11 @@ Clients
 
 .. currentmodule:: trio_websocket
 
-Context Managers
-----------------
+Creating A Client
+-----------------
 
 This page goes into the details of creating a WebSocket client. Let's start by
-revisiting the example from :ref:`client-tutorial`.
+revisiting the example from the :ref:`client-tutorial`.
 
 .. code-block:: python
     :linenos:
@@ -38,10 +38,13 @@ As explained in the tutorial, ``open_websocket_url(…)`` is a context manager
 that ensures the connection is properly opened and ready before entering the
 block. It also ensures that the connection is closed before exiting the block.
 This library contains two such context managers for creating client connections:
-one to connect by host/port/path and one to connect by URL.
+one to connect by host and one to connect by URL.
 
 .. autofunction:: open_websocket
+    :async-with: ws
+
 .. autofunction:: open_websocket_url
+    :async-with: ws
 
 Custom Nursery
 --------------

docs/conf.py

@@ -40,6 +40,7 @@
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.intersphinx',
+    'sphinxcontrib_trio',
 ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/credits.rst

@@ -0,0 +1,13 @@
+Credits
+=======
+
+Thanks to `John Belmonte (@belm0) <https://github.com/belm0>`__ and `Nathaniel
+J. Smith (@njsmith) <https://github.com/njsmith>`__ for lots of feedback,
+discussion, code reviews, and pull requests. Thanks to all the Trio contributors
+for making a fantastic framework! Thanks to Hyperion Gray for supporting
+development time on this project.
+
+.. image:: https://hyperiongray.s3.amazonaws.com/define-hg.svg
+    :target: https://www.hyperiongray.com/?pk_campaign=github&pk_kwd=agnostic
+    :alt: define hyperiongray
+    :width: 500px

docs/getting_started.rst

@@ -20,8 +20,8 @@ Change into the project directory and run the following command.
 
     $ pip3 install .
 
-If you want to contribute to development of the library, look at the
-documentation for :ref:`developer-installation`.
+If you want to contribute to development of the library, also see
+:ref:`developer-installation`.
 
 .. _client-tutorial:
 
@@ -52,7 +52,7 @@ The function :func:`open_websocket_url` is a context manager that automatically
 connects and performs the WebSocket handshake before entering the block. This
 ensures that the connection is usable before ``ws.send_message(…)`` is called.
 The context manager yields a :class:`WebSocketConnection` instance that is used
-to send and receive message. The context manager also closes the connection
+to send and receive messages. The context manager also closes the connection
 before exiting the block.
 
 For more details and examples, see :ref:`websocket-clients`.
@@ -63,8 +63,8 @@ Server Tutorial
 ---------------
 
 This example briefly demonstrates how to create a WebSocket server. This server
-is an *echo server*, i.e. it reads a message and then sends back the same
-message.
+is an *echo server*, i.e. it responds to each incoming message by sending back
+an identical message.
 
 .. code-block:: python
     :linenos:

docs/index.rst

@@ -35,3 +35,4 @@ Autobahn Test Suite <https://github.com/crossbario/autobahn-testsuite>`__.
    api
    recipes
    contributing
+   credits

docs/servers.rst

@@ -9,7 +9,7 @@ Creating A Server
 -----------------
 
 This page goes into the details of creating a WebSocket server. Let's start by
-revisiting the example from :ref:`server-tutorial`.
+revisiting the example from the :ref:`server-tutorial`.
 
 .. code-block:: python
     :linenos:
@@ -37,15 +37,15 @@ revisiting the example from :ref:`server-tutorial`.
     <https://github.com/HyperionGray/trio-websocket/blob/master/examples/server.py>`__.
 
 As explained in the tutorial, a WebSocket server needs a handler function and a
-host and port to bind to. The handler function receives a
-:class:`WebSocketRequest` object, and it calls ``accept()`` to finish the
-handshake and obtain a
+host/port to bind to. The handler function receives a
+:class:`WebSocketRequest` object, and it calls the request's
+:func:`~WebSocketRequest.accept` method to finish the handshake and obtain a
 :class:`WebSocketConnection` object.
 
 .. autofunction:: serve_websocket
 
-Serving Arbitrary Stream
-------------------------
+Custom Stream
+-------------
 
 The WebSocket protocol is defined as an application layer protocol that runs on
 top of TCP, and the convenience functions described above automatically create

setup.py

@@ -52,6 +52,7 @@
             'pytest-trio>=0.5.0',
             'sphinx',
             'sphinx_rtd_theme',
+            'sphinxcontrib-trio',
             'trustme',
         ],
     },