Merge branch 'branch2.4'

website/sphinx/conf.py

@@ -11,7 +11,12 @@
 
 version = release = tornado.version
 
-extensions = ["sphinx.ext.autodoc", "sphinx.ext.coverage", "sphinx.ext.viewcode"]
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.coverage",
+    "sphinx.ext.extlinks",
+    "sphinx.ext.viewcode",
+    ]
 
 primary_domain = 'py'
 default_role = 'py:obj'
@@ -82,3 +87,16 @@
 latex_documents = [
     ('index', 'tornado.tex', 'Tornado Documentation', 'Facebook', 'manual', False),
     ]
+
+# HACK: sphinx has limited support for substitutions with the |version|
+# variable, but there doesn't appear to be any way to use this in a link
+# target.
+# http://stackoverflow.com/questions/1227037/substitutions-inside-links-in-rest-sphinx
+# The extlink extension can be used to do link substitutions, but it requires a
+# portion of the url to be literally contained in the document.  Therefore,
+# this link must be referenced as :current_tarball:`z`
+extlinks = {
+    'current_tarball': (
+        'https://github.com/downloads/facebook/tornado/tornado-%s.tar.g%%s' % version,
+        'tornado-%s.tar.g' % version),
+    }

website/sphinx/documentation.rst

@@ -0,0 +1,21 @@
+Tornado Documentation
+=====================
+
+.. toctree::
+   :titlesonly:
+
+   overview
+   webframework
+   networking
+   integration
+   utilities
+   releases
+
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

website/sphinx/index.rst

@@ -1,21 +1,137 @@
-Tornado Documentation
-=====================
+.. title:: Tornado Web Server
+
+|Tornado Web Server|
+====================
+
+.. |Tornado Web Server| image:: tornado.png
+    :alt: Tornado Web Server
+
+`Tornado <http://www.tornadoweb.org/>`_ is an open source version of
+the scalable, non-blocking web server and tools that power `FriendFeed
+<http://friendfeed.com/>`_. The FriendFeed application is written
+using a web framework that looks a bit like `web.py
+<http://webpy.org/>`_ or `Google's webapp
+<http://code.google.com/appengine/docs/python/tools/webapp/>`_, but
+with additional tools and optimizations to take advantage of the
+underlying non-blocking infrastructure.
+
+The framework is distinct from most mainstream web server frameworks
+(and certainly most Python frameworks) because it is non-blocking and
+reasonably fast. Because it is non-blocking and uses `epoll
+<http://www.kernel.org/doc/man-pages/online/pages/man4/epoll.4.html>`_
+or ``kqueue``, it can handle thousands of simultaneous standing
+connections, which means it is ideal for real-time web services. We
+built the web server specifically to handle FriendFeed's real-time
+features &mdash; every active user of FriendFeed maintains an open
+connection to the FriendFeed servers. (For more information on scaling
+servers to support thousands of clients, see The `C10K problem
+<http://www.kegel.com/c10k.html>`_.)
+
+Upgrading from Tornado 1.x
+--------------------------
+
+Tornado 2.0 introduces several potentially backwards-incompatible
+changes, including in particular automatic escaping of template
+output.  Users who are upgrading from Tornado 1.x should see the
+`version 2.0 release notes </documentation/releases/v2.0.0.html>`_ for
+information about backwards compatibility.
+
+Quick links
+-----------
+
+* `Documentation <documentation.html>`_
+* |Download current version|: :current_tarball:`z` (`release notes </documentation/releases.html>`_)
+* `Source (github) <https://github.com/facebook/tornado>`_
+* `Mailing list <http://groups.google.com/group/python-tornado>`_
+* `Wiki <https://github.com/facebook/tornado/wiki/Links>`_
+
+.. |Download current version| replace:: Download version |version|
+
+Hello, world
+------------
+
+Here is the canonical "Hello, world" example app for Tornado::
+
+    import tornado.ioloop
+    import tornado.web
+
+    class MainHandler(tornado.web.RequestHandler):
+        def get(self):
+            self.write("Hello, world")
+
+    application = tornado.web.Application([
+        (r"/", MainHandler),
+    ])
+
+    if __name__ == "__main__":
+        application.listen(8888)
+        tornado.ioloop.IOLoop.instance().start()</code></pre>
+
+See the `Tornado documentation </documentation/index.html>`_ for a
+detailed walkthrough of the framework.
+
+Installation
+------------
+
+**Automatic installation:** Tornado is listed in `PyPI
+<http://pypi.python.org/pypi/tornado>`_ and can be installed with
+``pip`` or ``easy_install``.  Note that the source distribution
+includes demo applications that are not present when Tornado is
+installed in this way, so you may wish to download a copy of the
+source tarball as well.
+
+**Manual installation:** Download :current_tarball:`z`:
+
+.. parsed-literal::
+
+    tar xvzf tornado-|version|.tar.gz
+    cd tornado-|version|
+    python setup.py build
+    sudo python setup.py install
+
+The Tornado source code is `hosted on GitHub
+<https://github.com/facebook/tornado>`_.  On Python 2.6 and 2.7, it is
+also possible to simply add the tornado directory to your
+``PYTHONPATH`` instead of building with ``setup.py``, since the
+standard library includes ``epoll`` support.
+
+**Prerequisites:** Tornado runs on Python 2.5, 2.6, 2.7 and 3.2.
+
+* On Python 2.6 and 2.7, there are no dependencies outside the Python
+  standard library, although `PycURL
+  <http://pycurl.sourceforge.net/>`_ (version 7.18.2 or higher
+  required; version 7.21.1 or higher recommended) may be used if
+  desired.
+* On Python 2.5, PycURL is required, along with `simplejson
+  <http://pypi.python.org/pypi/simplejson/>`_ and the Python
+  development headers (typically obtained by installing a package
+  named something like ``python-dev`` from your operating system).
+* On Python 3.2, the `distribute
+  <http://pypi.python.org/pypi/distribute>`_ package is required.
+  Note that Python 3 support is relatively new and may have bugs.
+
+**Platforms:** Tornado should run on any Unix-like platform, although
+for the best performance and scalability only Linux and BSD (including
+BSD derivatives like Mac OS X) are recommended.
+
+Discussion and support
+----------------------
+
+You can discuss Tornado and report bugs on `the Tornado developer
+mailing list <http://groups.google.com/group/python-tornado>`_.  Links
+to additional resources can be found on the `Tornado wiki
+<https://github.com/facebook/tornado/wiki/Links>`_.
+
+Tornado is one of `Facebook's open source technologies
+<http://developers.facebook.com/opensource/>`_. It is available under
+the `Apache License, Version 2.0
+<http://www.apache.org/licenses/LICENSE-2.0.html>`_.
+
+This web site and all documentation is licensed under `Creative
+Commons 3.0 <http://creativecommons.org/licenses/by/3.0/>`_.
 
 .. toctree::
-   :titlesonly:
-
-   overview
-   webframework
-   networking
-   integration
-   utilities
-   releases
-
-
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+   :hidden:
+
+   documentation
+

website/static/sphinx.css

@@ -60,4 +60,8 @@ div.body {
 
 div.related, div.sphinxsidebar {
     font-family: Calibri, sans-serif;
+}
+
+div.section {
+    max-width: 850px;
 }