docs(ws-tutorial): add a WebSocket tutorial (#2245)

* docs(ws-tutorial): add tutorial on how to use websockets Add a tutorial on how to work with websockets in a Falcon app. This is to be read as a quickstart, linking to the reference page for more info. #2240 * docs(ws-tutorial): move example code to includable files Include the final code instead of hard-coding it in the docs. #2240 * docs(ws-tutorial): set max width to around 80 The max width is now set to 80. Not all lines fit, but most do. #2240 * docs(ws-tutorial): change authentication method for websockets Authentication is now done via the first-message method instead of headers. #2240 * docs(ws-tutorial): typo fix Typo fix. #2240 * docs(ws-tutorial): Do not generate coverage for the run command Do not generate coverage for the run command as that's only used when locally running the code. #2240 * docs(ws-tutorial): add explanation Add an explanation why the code isn't tested. #2240 * docs(ws-tutorial): add tests for the example code Add tests for the example code. #2240 * chore(wslook): shorten comment lines in `client.py` * style(wslook): shorten lines in `reports_client.py` * docs(tutorial-ws): sand some rough edges, fix CI * docs(WS): add more interlinks to the tutorial * chore: run tox -e wslook in CI * docs(ws-tutorial): add coveragerc to the repo --------- Co-authored-by: Vytautas Liuolia <[email protected]>
falconry · Jul 25, 2024 · cbca63d · cbca63d
1 parent 89b5fb0
commit cbca63d
Show file tree

Hide file tree

Showing 17 changed files with 767 additions and 0 deletions.
diff --git a/.github/workflows/tests.yaml b/.github/workflows/tests.yaml
@@ -35,6 +35,7 @@ jobs:
           - "towncrier"
           - "look"
           - "asgilook"
+          - "wslook"
           - "check_vendored"
           - "twine_check"
           - "daphne"

diff --git a/docs/api/websocket.rst b/docs/api/websocket.rst
@@ -424,6 +424,10 @@ by the framework.
     app = falcon.asgi.App(middleware=SomeMiddleware())
     app.add_route('/{account_id}/messages', SomeResource())
 
+.. tip::
+   If you prefer to learn by doing, feel free to continue experimenting along
+   the lines of our :ref:`WebSocket tutorial <tutorial-ws>`!
+
 Testing
 -------
 

diff --git a/docs/user/index.rst b/docs/user/index.rst
@@ -9,5 +9,6 @@ User Guide
    quickstart
    tutorial
    tutorial-asgi
+   tutorial-websockets
    recipes/index
    faq
diff --git a/docs/user/tutorial-asgi.rst b/docs/user/tutorial-asgi.rst
@@ -1033,6 +1033,10 @@ numerous ways:
   :ref:`WebSockets <ws>`.
 * ...And much more (patches welcome, as they say)!
 
+.. tip::
+   If you want to add :ref:`WebSocket <ws>` support, please check out our
+   :ref:`WebSocket tutorial <tutorial-ws>` too!
+
 Compared to the sync version, asynchronous code can at times be harder to
 design and reason about. Should you run into any issues, our friendly community
 is available to answer your questions and help you work through any sticky