Create docs #71
Create docs #71
Conversation
I've moved some content from README.md to the docs directory and also greatly expanded the content. I also noticed that I was unwisely using an Exception where a ValueError would be better, so I changed that and its corresponding unit test. After pushing this, I will set up Read The Docs.
* Published to RTD. * Proofread the previous commit. * Added sphinxcontrib-trio so that async APIs are documented correctly. * Added credits page.
The build fails because it can't find sphinxcontrib_trio, which is is a "dev" dependency. This quick fix is to make it a real dependency. This might be fixable by doing #61?
| tasks. If you wish to specify your own nursery instead, you should use the | ||
| the following convenience functions instead. | ||
|
|
||
| .. autofunction:: connect_websocket |
There was a problem hiding this comment.
Regarding the API naming: as the nursery for internal tasks is some implementation detail, it seems odd to use "open" vs. "connect" to qualify the function names, which suggests something different is being done with the connection.
Why not use a keyword argument on a common function?
There was a problem hiding this comment.
The open_* methods are context managers, and the connect_* methods are not.
This was discussed a bit in the client nursery issue. It was also discussed more in Gitter where Nathaniel described a potential use case for supplying a nursery: if the number of connections is determined dynamically, e.g. on one websocket you get a message that says "connect to this other websocket". In an earlier version, I had the nursery version as a keyword argument to a context manager, but this defeats the purpose of spawning new connections into the caller's nursery dynamically. I realize this explanation is a bit cloudy–to be honest I haven't tried writing code like this so it's cloudy in my head, too–but I still think this split between high level and low level APIs is worth keeping.
I don't like the names. The "open" and "connect" prefixes sound similar and don't suggest what might be different about them. I'm open to suggestions here...
| includes a convenience function that allows you to wrap any arbitrary Trio | ||
| stream with a client WebSocket. | ||
|
|
||
| .. autofunction:: wrap_client_stream |
There was a problem hiding this comment.
why doesn't wrap_client_stream have the nursery option?
There was a problem hiding this comment.
It does have a nursery argument. (The arguments are added by autofunction.)
| As explained in the tutorial, a WebSocket server needs a handler function and 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 |
There was a problem hiding this comment.
would you explain what to do if you didn't want to accept the connection, and maybe suggest how the decision would be made (e.g. by resource path?)
There was a problem hiding this comment.
At the moment, there's no way to reject the connection in an RFC compliant way. There are some hacks we could implement, but I'd prefer to wait until wsproto supports this upstream so we can do it right. (Have you looked at python-hyper/wsproto/issues/85?)
This PR includes documentation in Sphinx format, published to Read The Docs here:
https://trio-websocket.readthedocs.io/
This should be pretty complete and I've proofread for grammar issues, broken links, etc. It could use a quick review for clarity and omissions.