Repository: encode/starlette
Pull request: Add `WebSocketRoute` docs in `Routing`
Closes #764 .

Currently we have two examples of `WebSocketRoute` in applications and endpoints, but they don't document the `WebSocketRoute`.

I've included the `endpoint` argument in the docs and pointed general features like Path Parameters, Reverse URL Lookups and etc. to the Route docs.



Problem statement:
WebSocketRoute undocumented
The "routing" docs page doesn't mention that `Route()` is for HTTP only and `WebSocketRoute()` is required for websocket endpoints. I found `WebSocketRoute` through examples on other pages but it woudl be good if it was fully described on the "routing" page.

Hints from issue discussion:

Commit message: Add WebSocketRoute docs

Patch to review:
diff --git a/docs/routing.md b/docs/routing.md
index f19c57b70..10cd04724 100644
--- a/docs/routing.md
+++ b/docs/routing.md
@@ -1,3 +1,5 @@
+## HTTP Routing
+
 Starlette has a simple but capable request routing system. A routing table
 is defined as a list of routes, and passed when instantiating the application.
 
@@ -26,8 +28,7 @@ The `endpoint` argument can be one of:
 
 * A regular function or async function, which accepts a single `request`
 argument and which should return a response.
-* A class that implements the ASGI interface, such as Starlette's [class based
-views](endpoints.md).
+* A class that implements the ASGI interface, such as Starlette's [HTTPEndpoint](endpoints.md).
 
 ## Path Parameters
 
@@ -262,3 +263,42 @@ app = Router(routes=[
     ])
 ])
 ```
+
+## WebSocket Routing
+
+When working with WebSocket endpoints, you should use `WebSocketRoute`
+instead of the usual `Route`.
+
+Path parameters, and reverse URL lookups for `WebSocketRoute` work the the same
+as HTTP `Route`, which can be found in the [Route](#path-parameters) documentation.
+
+```python
+from starlette.applications import Starlette
+from starlette.routing import WebSocketRoute
+
+
+async def websocket_index(websocket):
+    await websocket.accept()
+    await websocket.send_text("Hello, websocket!")
+    await websocket.close()
+
+
+async def websocket_user(websocket):
+    name = websocket.path_params["name"]
+    await websocket.accept()
+    await websocket.send_text(f"Hello, {name}")
+    await websocket.close()
+
+
+routes = [
+    WebSocketRoute("/", endpoint=websocket_index),
+    WebSocketRoute("/{name}", endpoint=websocket_user),
+]
+
+app = Starlette(routes=routes)
+```
+
+The `endpoint` argument can be one of:
+
+* An async function, which accepts a single `websocket` argument.
+* A class that implements the ASGI interface, such as Starlette's [WebSocketEndpoint](endpoints.md).


Code review comments:
diff_hunk: @@ -262,3 +263,42 @@ app = Router(routes=[
     ])
 ])
 ```
+
+## WebSocket Routing
+
+When working with WebSocket endpoints, you should use `WebSocketRoute`
+instead of the usual `Route`.
+
+Path parameters, and reverse URL lookups for `WebSocketRoute` work the the same
+as HTTP `Route`, which can be found in the [Route](#path-parameters) documentation.
path: docs/routing.md
text: @user1:
Looks weird talking about it like if it was in another location, but in reality, it's actually above :thinking:

Can we rephrase this last part (after the last comma)? Something like "like mentioned in the section [Path parameters](#path-parameters) above", or something like that?

If you disagree, feel free to close this thread :+1: 

@author:
I agree with making it obvious they're on the same page.
Another point, since we're linking multiple things (path params, url lookups, ..), what do you think instead we link it to the `HTTP Routing` section? It's not really accurate to point to path parameters.

@user1:
Sure :+1: