Merge pull request #2586 from sadielbartholomew/minor-docs-improvements

docs: assorted minor e.g. formatting improvements

Author: bdarnell

docs/faq.rst

@@ -74,8 +74,8 @@ See the :doc:`Asynchronous I/O <guide/async>` chapter of the Tornado
 user's guide for more on blocking and asynchronous functions.
 
 
-My code is asynchronous, but it's not running in parallel in two browser tabs.
-------------------------------------------------------------------------------
+My code is asynchronous. Why is it not running in parallel in two browser tabs?
+-------------------------------------------------------------------------------
 
 Even when a handler is asynchronous and non-blocking, it can be surprisingly
 tricky to verify this. Browsers will recognize that you are trying to

docs/guide/coroutines.rst

@@ -39,7 +39,7 @@ decorator.
 
 Native coroutines are the recommended form whenever possible. Only use
 decorated coroutines when compatibility with older versions of Python
-is required. Examples in the tornado documentation will generally use
+is required. Examples in the Tornado documentation will generally use
 the native form.
 
 Translation between the two forms is generally straightforward::
@@ -58,30 +58,35 @@ Translation between the two forms is generally straightforward::
         # special exception.            # Return normally
         raise gen.Return(b)             return b
 
-Other differences between the two forms of coroutine are:
-
-- Native coroutines are generally faster.
-- Native coroutines can use ``async for`` and ``async with``
-  statements which make some patterns much simpler.
-- Native coroutines do not run at all unless you ``await`` or
-  ``yield`` them. Decorated coroutines can start running "in the
-  background" as soon as they are called. Note that for both kinds of
-  coroutines it is important to use ``await`` or ``yield`` so that
-  any exceptions have somewhere to go.
-- Decorated coroutines have additional integration with the
-  `concurrent.futures` package, allowing the result of
-  ``executor.submit`` to be yielded directly. For native coroutines,
-  use `.IOLoop.run_in_executor` instead.
-- Decorated coroutines support some shorthand for waiting on multiple
-  objects by yielding a list or dict. Use `tornado.gen.multi` to do
-  this in native coroutines.
-- Decorated coroutines can support integration with other packages
-  including Twisted via a registry of conversion functions.
-  To access this functionality in native coroutines, use
-  `tornado.gen.convert_yielded`.
-- Decorated coroutines always return a `.Future` object. Native
-  coroutines return an *awaitable* object that is not a `.Future`. In
-  Tornado the two are mostly interchangeable.
+Other differences between the two forms of coroutine are outlined below.
+
+- Native coroutines:
+
+  - are generally faster.
+  - can use ``async for`` and ``async with``
+    statements which make some patterns much simpler.
+  - do not run at all unless you ``await`` or
+    ``yield`` them. Decorated coroutines can start running "in the
+    background" as soon as they are called. Note that for both kinds of
+    coroutines it is important to use ``await`` or ``yield`` so that
+    any exceptions have somewhere to go.
+
+- Decorated coroutines:
+
+  - have additional integration with the
+    `concurrent.futures` package, allowing the result of
+    ``executor.submit`` to be yielded directly. For native coroutines,
+    use `.IOLoop.run_in_executor` instead.
+  - support some shorthand for waiting on multiple
+    objects by yielding a list or dict. Use `tornado.gen.multi` to do
+    this in native coroutines.
+  - can support integration with other packages
+    including Twisted via a registry of conversion functions.
+    To access this functionality in native coroutines, use
+    `tornado.gen.convert_yielded`.
+  - always return a `.Future` object. Native
+    coroutines return an *awaitable* object that is not a `.Future`. In
+    Tornado the two are mostly interchangeable.
 
 How it works
 ~~~~~~~~~~~~

docs/guide/intro.rst

@@ -29,4 +29,4 @@ alternative to `WSGI <http://www.python.org/dev/peps/pep-3333/>`_.
 While it is possible to use the Tornado HTTP server as a container for
 other WSGI frameworks (`.WSGIContainer`), this combination has
 limitations and to take full advantage of Tornado you will need to use
-the Tornado's web framework and HTTP server together.
+Tornado's web framework and HTTP server together.

docs/guide/running.rst

@@ -22,8 +22,9 @@ configuring a WSGI container to find your application, you write a
 Configure your operating system or process manager to run this program to
 start the server. Please note that it may be necessary to increase the number 
 of open files per process (to avoid "Too many open files"-Error). 
-To raise this limit (setting it to 50000 for example)  you can use the ulimit command, 
-modify /etc/security/limits.conf or setting ``minfds`` in your supervisord config.
+To raise this limit (setting it to 50000 for example)  you can use the
+``ulimit`` command, modify ``/etc/security/limits.conf`` or set
+``minfds`` in your `supervisord <http://www.supervisord.org>`_ config.
 
 Processes and ports
 ~~~~~~~~~~~~~~~~~~~
@@ -50,8 +51,8 @@ main function:
 
 This is the easiest way to start multiple processes and have them all
 share the same port, although it has some limitations.  First, each
-child process will have its own IOLoop, so it is important that
-nothing touch the global IOLoop instance (even indirectly) before the
+child process will have its own ``IOLoop``, so it is important that
+nothing touches the global ``IOLoop`` instance (even indirectly) before the
 fork.  Second, it is difficult to do zero-downtime updates in this model.
 Finally, since all the processes share the same port it is more difficult
 to monitor them individually.
@@ -67,10 +68,10 @@ to present a single address to outside visitors.
 Running behind a load balancer
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-When running behind a load balancer like nginx, it is recommended to
-pass ``xheaders=True`` to the `.HTTPServer` constructor. This will tell
-Tornado to use headers like ``X-Real-IP`` to get the user's IP address
-instead of attributing all traffic to the balancer's IP address.
+When running behind a load balancer like `nginx <http://nginx.net/>`_,
+it is recommended to pass ``xheaders=True`` to the `.HTTPServer` constructor.
+This will tell Tornado to use headers like ``X-Real-IP`` to get the user's
+IP address instead of attributing all traffic to the balancer's IP address.
 
 This is a barebones nginx config file that is structurally similar to
 the one we use at FriendFeed. It assumes nginx and the Tornado servers
@@ -169,7 +170,7 @@ You can serve static files from Tornado by specifying the
     ], **settings)
 
 This setting will automatically make all requests that start with
-``/static/`` serve from that static directory, e.g.,
+``/static/`` serve from that static directory, e.g.
 ``http://localhost:8888/static/foo.png`` will serve the file
 ``foo.png`` from the specified static directory. We also automatically
 serve ``/robots.txt`` and ``/favicon.ico`` from the static directory
@@ -248,7 +249,7 @@ individual flag takes precedence):
   server down in a way that debug mode cannot currently recover from.
 * ``compiled_template_cache=False``: Templates will not be cached.
 * ``static_hash_cache=False``: Static file hashes (used by the
-  ``static_url`` function) will not be cached
+  ``static_url`` function) will not be cached.
 * ``serve_traceback=True``: When an exception in a `.RequestHandler`
   is not caught, an error page including a stack trace will be
   generated.

docs/guide/structure.rst

@@ -178,7 +178,7 @@ In addition to ``get()``/``post()``/etc, certain other methods in
 necessary. On every request, the following sequence of calls takes
 place:
 
-1. A new `.RequestHandler` object is created on each request
+1. A new `.RequestHandler` object is created on each request.
 2. `~.RequestHandler.initialize()` is called with the initialization
    arguments from the `.Application` configuration. ``initialize``
    should typically just save the arguments passed into member
@@ -206,12 +206,12 @@ overridden methods include:
   disconnects; applications may choose to detect this case and halt
   further processing.  Note that there is no guarantee that a closed
   connection can be detected promptly.
-- `~.RequestHandler.get_current_user` - see :ref:`user-authentication`
+- `~.RequestHandler.get_current_user` - see :ref:`user-authentication`.
 - `~.RequestHandler.get_user_locale` - returns `.Locale` object to use
-  for the current user
+  for the current user.
 - `~.RequestHandler.set_default_headers` - may be used to set
   additional headers on the response (such as a custom ``Server``
-  header)
+  header).
 
 Error Handling
 ~~~~~~~~~~~~~~
@@ -260,7 +260,7 @@ redirect users elsewhere. There is also an optional parameter
 considered permanent.  The default value of ``permanent`` is
 ``False``, which generates a ``302 Found`` HTTP response code and is
 appropriate for things like redirecting users after successful
-``POST`` requests.  If ``permanent`` is true, the ``301 Moved
+``POST`` requests.  If ``permanent`` is ``True``, the ``301 Moved
 Permanently`` HTTP response code is used, which is useful for
 e.g. redirecting to a canonical URL for a page in an SEO-friendly
 manner.

docs/guide/templates.rst

@@ -66,9 +66,9 @@ directory as your Python file, you could render this template with:
    :hide:
 
 Tornado templates support *control statements* and *expressions*.
-Control statements are surrounded by ``{%`` and ``%}``, e.g.,
+Control statements are surrounded by ``{%`` and ``%}``, e.g.
 ``{% if len(items) > 2 %}``. Expressions are surrounded by ``{{`` and
-``}}``, e.g., ``{{ items[0] }}``.
+``}}``, e.g. ``{{ items[0] }}``.
 
 Control statements more or less map exactly to Python statements. We
 support ``if``, ``for``, ``while``, and ``try``, all of which are
@@ -78,7 +78,7 @@ detail in the documentation for the `tornado.template`.
 
 Expressions can be any Python expression, including function calls.
 Template code is executed in a namespace that includes the following
-objects and functions (Note that this list applies to templates
+objects and functions. (Note that this list applies to templates
 rendered using `.RequestHandler.render` and
 `~.RequestHandler.render_string`. If you're using the
 `tornado.template` module directly outside of a `.RequestHandler` many
@@ -136,7 +136,8 @@ that appear in certain locations, such as in Javascript or CSS, may need
 additional escaping.  Additionally, either care must be taken to always
 use double quotes and `.xhtml_escape` in HTML attributes that may contain
 untrusted content, or a separate escaping function must be used for
-attributes (see e.g. http://wonko.com/post/html-escaping)
+attributes (see e.g.
+`this blog post <http://wonko.com/post/html-escaping>`_).
 
 Internationalization
 ~~~~~~~~~~~~~~~~~~~~
@@ -212,7 +213,7 @@ formats: the ``.mo`` format used by `gettext` and related tools, and a
 simple ``.csv`` format.  An application will generally call either
 `tornado.locale.load_translations` or
 `tornado.locale.load_gettext_translations` once at startup; see those
-methods for more details on the supported formats..
+methods for more details on the supported formats.
 
 You can get the list of supported locales in your application with
 `tornado.locale.get_supported_locales()`. The user's locale is chosen
@@ -234,7 +235,7 @@ packaged with their own CSS and JavaScript.
 For example, if you are implementing a blog, and you want to have blog
 entries appear on both the blog home page and on each blog entry page,
 you can make an ``Entry`` module to render them on both pages. First,
-create a Python module for your UI modules, e.g., ``uimodules.py``::
+create a Python module for your UI modules, e.g. ``uimodules.py``::
 
     class Entry(tornado.web.UIModule):
         def render(self, entry, show_comments=False):

docs/index.rst

@@ -21,7 +21,7 @@ Quick links
 -----------
 
 * Current version: |version| (`download from PyPI <https://pypi.python.org/pypi/tornado>`_, :doc:`release notes <releases>`)
-* `Source (github) <https://github.com/tornadoweb/tornado>`_
+* `Source (GitHub) <https://github.com/tornadoweb/tornado>`_
 * Mailing lists: `discussion <http://groups.google.com/group/python-tornado>`_ and `announcements <http://groups.google.com/group/python-tornado-announce>`_
 * `Stack Overflow <http://stackoverflow.com/questions/tagged/tornado>`_
 * `Wiki <https://github.com/tornadoweb/tornado/wiki/Links>`_

docs/web.rst

@@ -28,7 +28,7 @@
    The arguments to these methods come from the `.URLSpec`: Any
    capturing groups in the regular expression become arguments to the
    HTTP verb methods (keyword arguments if the group is named,
-   positional arguments if its unnamed).
+   positional arguments if it's unnamed).
 
    To support a method not on this list, override the class variable
    ``SUPPORTED_METHODS``::
@@ -159,7 +159,8 @@
 
 
    Application configuration
-   -----------------------------
+   -------------------------
+
    .. autoclass:: Application(handlers: List[Union[Rule, Tuple]] = None, default_host: str = None, transforms: List[Type[OutputTransform]] = None, **settings)
 
       .. attribute:: settings
@@ -197,7 +198,7 @@
            `RequestHandler` object).  The default implementation
            writes to the `logging` module's root logger.  May also be
            customized by overriding `Application.log_request`.
-         * ``serve_traceback``: If true, the default error page
+         * ``serve_traceback``: If ``True``, the default error page
            will include the traceback of the error.  This option is new in
            Tornado 3.2; previously this functionality was controlled by
            the ``debug`` setting.
@@ -224,7 +225,7 @@
          * ``login_url``: The `authenticated` decorator will redirect
            to this url if the user is not logged in.  Can be further
            customized by overriding `RequestHandler.get_login_url`
-         * ``xsrf_cookies``: If true, :ref:`xsrf` will be enabled.
+         * ``xsrf_cookies``: If ``True``, :ref:`xsrf` will be enabled.
          * ``xsrf_cookie_version``: Controls the version of new XSRF
            cookies produced by this server.  Should generally be left
            at the default (which will always be the highest supported

tornado/auth.py

@@ -840,7 +840,7 @@ class GoogleOAuth2Mixin(OAuth2Mixin):
     * In the OAuth section of the page, select Create New Client ID.
     * Set the Redirect URI to point to your auth handler
     * Copy the "Client secret" and "Client ID" to the application settings as
-      {"google_oauth": {"key": CLIENT_ID, "secret": CLIENT_SECRET}}
+      ``{"google_oauth": {"key": CLIENT_ID, "secret": CLIENT_SECRET}}``
 
     .. versionadded:: 3.2
     """

tornado/concurrent.py

@@ -176,7 +176,7 @@ def future_set_result_unless_cancelled(
 ) -> None:
     """Set the given ``value`` as the `Future`'s result, if not cancelled.
 
-    Avoids asyncio.InvalidStateError when calling set_result() on
+    Avoids ``asyncio.InvalidStateError`` when calling ``set_result()`` on
     a cancelled `asyncio.Future`.
 
     .. versionadded:: 5.0
@@ -192,10 +192,10 @@ def future_set_exception_unless_cancelled(
 
     If the Future is already canceled, logs the exception instead. If
     this logging is not desired, the caller should explicitly check
-    the state of the Future and call Future.set_exception instead of
+    the state of the Future and call ``Future.set_exception`` instead of
     this wrapper.
 
-    Avoids asyncio.InvalidStateError when calling set_exception() on
+    Avoids ``asyncio.InvalidStateError`` when calling ``set_exception()`` on
     a cancelled `asyncio.Future`.
 
     .. versionadded:: 6.0
@@ -223,7 +223,7 @@ def future_set_exc_info(
     .. versionchanged:: 6.0
 
        If the future is already cancelled, this function is a no-op.
-       (previously asyncio.InvalidStateError would be raised)
+       (previously ``asyncio.InvalidStateError`` would be raised)
 
     """
     if exc_info[1] is None: