More doc updates

bdarnell · bdarnell · commit cdc76f2fb1d8 · 2011-06-16T22:36:33.000-07:00
diff --git a/tornado/escape.py b/tornado/escape.py
@@ -14,7 +14,11 @@
 # License for the specific language governing permissions and limitations
 # under the License.
 
-"""Escaping/unescaping methods for HTML, JSON, URLs, and others."""
+"""Escaping/unescaping methods for HTML, JSON, URLs, and others.
+
+Also includes a few other miscellaneous string manipulation functions that
+have crept in over time.
+"""
 
 import htmlentitydefs
 import re
@@ -221,8 +225,8 @@ def linkify(text, shorten=False, extra_params="",
             require_protocol=False, permitted_protocols=["http", "https"]):
     """Converts plain text into HTML with links.
 
-    For example: linkify("Hello http://tornadoweb.org!") would return
-    Hello <a href="http://tornadoweb.org">http://tornadoweb.org</a>!
+    For example: ``linkify("Hello http://tornadoweb.org!")`` would return
+    ``Hello <a href="http://tornadoweb.org">http://tornadoweb.org</a>!``
 
     Parameters:
 
diff --git a/tornado/httpserver.py b/tornado/httpserver.py
@@ -14,7 +14,15 @@
 # License for the specific language governing permissions and limitations
 # under the License.
 
-"""A non-blocking, single-threaded HTTP server."""
+"""A non-blocking, single-threaded HTTP server.
+
+Typical applications have little direct interaction with the `HTTPServer`
+class except to start a server at the beginning of the process
+(and even that is often done indirectly via `tornado.web.Application.listen`).
+
+This module also defines the `HTTPRequest` class which is exposed via
+`tornado.web.RequestHandler.request`.
+"""
 
 import errno
 import logging
@@ -418,20 +426,72 @@ def _on_request_body(self, data):
 class HTTPRequest(object):
     """A single HTTP request.
 
-    GET/POST arguments are available in the arguments property, which
-    maps arguments names to lists of values (to support multiple values
-    for individual names). Names and values are both unicode always.
+    .. attribute:: method
+
+       HTTP request method, e.g. "GET" or "POST"
+
+    .. attribute:: uri
+
+       The requested uri.
+
+    .. attribute:: path
+
+       The path portion of `uri`
+
+    .. attribute:: query
+
+       The query portion of `uri`
+
+    .. attribute:: version
+
+       HTTP version specified in request, e.g. "HTTP/1.1"
+
+    .. attribute:: headers
+
+       `HTTPHeader` dictionary-like object for request headers.  Acts like
+       a case-insensitive dictionary with additional methods for repeated
+       headers.
+
+    .. attribute:: body
+
+       Request body, if present.
+
+    .. attribute:: remote_ip
+
+       Client's IP address as a string.  If `HTTPServer.xheaders` is set,
+       will pass along the real IP address provided by a load balancer
+       in the ``X-Real-Ip`` header
+
+    .. attribute:: protocol
+
+       The protocol used, either "http" or "https".  If `HTTPServer.xheaders`
+       is seet, will pass along the protocol used by a load balancer if
+       reported via an ``X-Scheme`` header.
+
+    .. attribute:: host
+
+       The requested hostname, usually taken from the ``Host`` header.
+
+    .. attribute:: arguments
+
+       GET/POST arguments are available in the arguments property, which
+       maps arguments names to lists of values (to support multiple values
+       for individual names). Names and values are both unicode always.
+
+    .. attribute:: files
+
+       File uploads are available in the files property, which maps file
+       names to list of files. Each file is a dictionary of the form
+       {"filename":..., "content_type":..., "body":...}. The content_type
+       comes from the provided HTTP header and should not be trusted
+       outright given that it can be easily forged.
 
-    File uploads are available in the files property, which maps file
-    names to list of files. Each file is a dictionary of the form
-    {"filename":..., "content_type":..., "body":...}. The content_type
-    comes from the provided HTTP header and should not be trusted
-    outright given that it can be easily forged.
+    .. attribute:: connection
 
-    An HTTP request is attached to a single HTTP connection, which can
-    be accessed through the "connection" attribute. Since connections
-    are typically kept open in HTTP/1.1, multiple requests can be handled
-    sequentially on a single connection.
+       An HTTP request is attached to a single HTTP connection, which can
+       be accessed through the "connection" attribute. Since connections
+       are typically kept open in HTTP/1.1, multiple requests can be handled
+       sequentially on a single connection.
     """
     def __init__(self, method, uri, version="HTTP/1.0", headers=None,
                  body=None, remote_ip=None, protocol=None, host=None,
diff --git a/tornado/template.py b/tornado/template.py
@@ -77,6 +77,11 @@ def add(x, y):
 
 We provide the functions escape(), url_escape(), json_encode(), and squeeze()
 to all templates by default.
+
+Typical applications do not create `Template` or `Loader` instances by
+hand, but instead use the `render` and `render_string` methods of
+`tornado.web.RequestHandler`, which load templates automatically based
+on the ``template_path`` `Application` setting.
 """
 
 from __future__ import with_statement
diff --git a/tornado/web.py b/tornado/web.py
@@ -121,6 +121,7 @@ def initialize(self):
         supplied as keyword arguments to initialize().
 
         Example::
+
             class ProfileHandler(RequestHandler):
                 def initialize(self, database):
                     self.database = database
@@ -136,6 +137,7 @@ def get(self, username):
 
     @property
     def settings(self):
+        """An alias for `self.application.settings`."""
         return self.application.settings
 
     def head(self, *args, **kwargs):
@@ -1086,6 +1088,12 @@ class Application(object):
     keyword argument. We will serve those files from the /static/ URI
     (this is configurable with the static_url_prefix setting),
     and we will serve /favicon.ico and /robots.txt from the same directory.
+
+    .. attribute:: settings
+
+       Additonal keyword arguments passed to the constructor are saved in the
+       `settings` dictionary, and are often referred to in documentation as
+       "application settings".
     """
     def __init__(self, handlers=None, default_host="", transforms=None,
                  wsgi=False, **settings):
diff --git a/website/Makefile b/website/Makefile
@@ -1,4 +1,5 @@
-SPHINXOPTS=-d sphinx/build/doctrees sphinx
+SPHINXOPTS=-W -d sphinx/build/doctrees sphinx
+
 .PHONY: sphinx
 sphinx:
 	sphinx-build -b html $(SPHINXOPTS) sphinx/build/html
diff --git a/website/sphinx/conf.py b/website/sphinx/conf.py
@@ -15,7 +15,10 @@
 
 version = release = tornado.version
 
-extensions = ["sphinx.ext.autodoc", "sphinx_coverage"]
+extensions = ["sphinx.ext.autodoc", "sphinx_coverage", "sphinx.ext.viewcode"]
+
+primary_domain = 'py'
+default_role = 'py:obj'
 
 autodoc_member_order = "bysource"
 autoclass_content = "both"
diff --git a/website/sphinx/escape.rst b/website/sphinx/escape.rst
@@ -2,4 +2,38 @@
 =======================================================
 
 .. automodule:: tornado.escape
-   :members:
+
+   Escaping functions
+   ------------------
+
+   .. autofunction:: xhtml_escape
+   .. autofunction:: xhtml_unescape
+
+   .. autofunction:: url_escape
+   .. autofunction:: url_unescape
+
+   .. autofunction:: json_encode
+   .. autofunction:: json_decode
+
+   Byte/unicode conversions
+   ------------------------
+   These functions are used extensively within Tornado itself,
+   but should not be directly needed by most applications.  Note that 
+   much of the complexity of these functions comes from the fact that
+   Tornado supports both Python 2 and Python 3.
+
+   .. autofunction:: utf8
+   .. autofunction:: to_unicode
+   .. function:: native_str
+
+      Converts a byte or unicode string into type `str`.  Equivalent to
+      `utf8` on Python 2 and `to_unicode` on Python 3.
+
+   .. autofunction:: to_basestring
+
+   .. autofunction:: recursive_unicode
+
+   Miscellaneous functions
+   -----------------------
+   .. autofunction:: linkify
+   .. autofunction:: squeeze
diff --git a/website/sphinx/httpserver.rst b/website/sphinx/httpserver.rst
@@ -2,4 +2,13 @@
 ===================================================
 
 .. automodule:: tornado.httpserver
-   :members:
+
+   ``HTTPRequest`` objects
+   -----------------------
+   .. autoclass:: HTTPRequest
+      :members:
+
+   HTTP Server
+   -----------
+   .. autoclass:: HTTPServer
+   .. autoclass:: HTTPConnection
diff --git a/website/sphinx/template.rst b/website/sphinx/template.rst
@@ -2,4 +2,4 @@
 ===================================================
 
 .. automodule:: tornado.template
-   :members:
+   :members:   
diff --git a/website/sphinx/web.rst b/website/sphinx/web.rst
@@ -29,6 +29,10 @@
    .. automethod:: RequestHandler.get_argument
    .. automethod:: RequestHandler.get_arguments
    .. automethod:: RequestHandler.decode_argument
+   .. attribute:: RequestHandler.request
+
+      The `tornado.httpserver.HTTPRequest` object containing additional
+      request parameters including e.g. headers and body data.
 
    Output
    ^^^^^^
@@ -61,6 +65,10 @@
    Other
    ^^^^^
 
+   .. attribute:: RequestHandler.application
+
+      The `Application` object serving this request
+
    .. automethod:: RequestHandler.async_callback
    .. automethod:: RequestHandler.check_xsrf_cookie
    .. automethod:: RequestHandler.compute_etag
@@ -72,6 +80,7 @@
    .. automethod:: RequestHandler.get_user_locale
    .. automethod:: RequestHandler.on_connection_close
    .. automethod:: RequestHandler.require_setting
+   .. autoattribute:: RequestHandler.settings
    .. automethod:: RequestHandler.static_url
    .. automethod:: RequestHandler.xsrf_form_html
 
