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 (file)
index 0000000..1021254
--- /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 ad927606bf9d0b30c62a2996642bc66f3aed5528..d120ea407ab7331d9a5849c0344dfda7a2dd8948 100644 (file)
--- 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 377ae42b9e7a78522520098f784e6c6cedf3411f..3837d4c4f910706557a3541df103e10469298cd7 100644 (file)
--- 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 5a4ce9e258410970f2e2d821d7c209639f232c66..831fe5ce0e2a7f293daeb7e406a5f12e7ef93d40 100644 (file)
--- 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 c4f8836770567885253d6288cfc75f5287fc7774..18634d8959c666bd4b6913ceb32abc3985bb7043 100644 (file)
--- 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):