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

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.
+

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

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.

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.
 

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):