From: Ben Darnell <ben@bendarnell.com>
Date: Tue, 21 Feb 2023 21:34:38 +0000 (+0000)
Subject: docs: Point to stable branch for all demo links
X-Git-Tag: v6.3.0b1~6^2
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F3238%2Fhead;p=thirdparty%2Ftornado.git

docs: Point to stable branch for all demo links

Add a README to the demos directory with a brief description of each,
and a warning about the usage of not-yet-released features.

Fixes #3236
---

diff --git a/demos/README.rst b/demos/README.rst
new file mode 100644
index 000000000..102125479
--- /dev/null
+++ b/demos/README.rst
@@ -0,0 +1,40 @@
+Tornado Demo Apps
+-----------------
+
+This directory contains several example apps that illustrate the usage of
+various Tornado features. If you're not sure where to start, try the ``chat``,
+``blog``, or ``websocket`` demos.
+
+.. note::
+
+    These applications require features due to be introduced in Tornado 6.3
+    which is not yet released. Unless you are testing the new release,
+    use the GitHub branch selector to access the ``stable`` branch
+    (or the ``branchX.y`` branch corresponding to the version of Tornado you
+    are using) to get a suitable version of the demos.
+
+    TODO: remove this when 6.3 ships.
+
+Web Applications
+~~~~~~~~~~~~~~~~
+
+- ``blog``: A simple database-backed blogging platform, including
+  HTML templates and authentication.
+- ``chat``: A chat room demonstrating live updates via long polling.
+- ``websocket``: Similar to ``chat`` but with WebSockets instead of
+  long polling.
+- ``helloworld``: The simplest possible Tornado web page.
+- ``s3server``: Implements a basic subset of the Amazon S3 API.
+
+Feature demos
+~~~~~~~~~~~~~
+
+- ``facebook``: Authentication with the Facebook Graph API.
+- ``twitter``: Authentication with the Twitter API.
+- ``file_upload``: Client and server support for streaming HTTP request 
+  payloads.
+- ``tcpecho``: Using the lower-level ``IOStream`` interfaces for non-HTTP
+  networking.
+- ``webspider``: Concurrent usage of ``AsyncHTTPClient``, using queues and
+  semaphores.
+
diff --git a/docs/guide/structure.rst b/docs/guide/structure.rst
index ad927606b..d120ea407 100644
--- a/docs/guide/structure.rst
+++ b/docs/guide/structure.rst
@@ -176,7 +176,7 @@ handle files that are too large to comfortably keep in memory see the
 `.stream_request_body` class decorator.
 
 In the demos directory,
-`file_receiver.py <https://github.com/tornadoweb/tornado/tree/master/demos/file_upload/>`_
+`file_receiver.py <https://github.com/tornadoweb/tornado/tree/stable/demos/file_upload/>`_
 shows both methods of receiving file uploads.
 
 Due to the quirks of the HTML form encoding (e.g. the ambiguity around
diff --git a/docs/httpclient.rst b/docs/httpclient.rst
index 377ae42b9..3837d4c4f 100644
--- a/docs/httpclient.rst
+++ b/docs/httpclient.rst
@@ -70,7 +70,7 @@ Implementations
 Example Code
 ~~~~~~~~~~~~
 
-* `A simple webspider <https://github.com/tornadoweb/tornado/blob/master/demos/webspider/webspider.py>`_
+* `A simple webspider <https://github.com/tornadoweb/tornado/blob/stable/demos/webspider/webspider.py>`_
   shows how to fetch URLs concurrently.
-* `The file uploader demo <https://github.com/tornadoweb/tornado/tree/master/demos/file_upload/>`_
+* `The file uploader demo <https://github.com/tornadoweb/tornado/tree/stable/demos/file_upload/>`_
   uses either HTTP POST or HTTP PUT to upload files to a server.
diff --git a/docs/releases/v4.5.0.rst b/docs/releases/v4.5.0.rst
index 5a4ce9e25..831fe5ce0 100644
--- a/docs/releases/v4.5.0.rst
+++ b/docs/releases/v4.5.0.rst
@@ -178,10 +178,10 @@ Demos
 ~~~~~
 
 - A new file upload demo is available in the `file_upload
-  <https://github.com/tornadoweb/tornado/tree/master/demos/file_upload>`_
+  <https://github.com/tornadoweb/tornado/tree/stable/demos/file_upload>`_
   directory.
 - A new `.TCPClient` and `.TCPServer` demo is available in the
-  `tcpecho <https://github.com/tornadoweb/tornado/tree/master/demos/tcpecho>`_ directory.
+  `tcpecho <https://github.com/tornadoweb/tornado/tree/stable/demos/tcpecho>`_ directory.
 - Minor updates have been made to several existing demos, including
   updates to more recent versions of jquery.
 
diff --git a/tornado/web.py b/tornado/web.py
index c4f883677..18634d895 100644
--- a/tornado/web.py
+++ b/tornado/web.py
@@ -1904,7 +1904,7 @@ def stream_request_body(cls: Type[_RequestHandlerType]) -> Type[_RequestHandlerT
     * The regular HTTP method (``post``, ``put``, etc) will be called after
       the entire body has been read.
 
-    See the `file receiver demo <https://github.com/tornadoweb/tornado/tree/master/demos/file_upload/>`_
+    See the `file receiver demo <https://github.com/tornadoweb/tornado/tree/stable/demos/file_upload/>`_
     for example usage.
     """  # noqa: E501
     if not issubclass(cls, RequestHandler):