From: Ben Darnell Date: Sun, 10 Mar 2013 18:25:06 +0000 (-0400) Subject: Add a sphinx/rst version of the tornadoweb.org index page. (WIP) X-Git-Tag: v3.0.0~45^2~2 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=11af37659a4fc92299520a39e7e2e99e7eed4551;p=thirdparty%2Ftornado.git Add a sphinx/rst version of the tornadoweb.org index page. (WIP) --- diff --git a/website/sphinx/documentation.rst b/website/sphinx/documentation.rst new file mode 100644 index 000000000..f07460b72 --- /dev/null +++ b/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` diff --git a/website/sphinx/index.rst b/website/sphinx/index.rst index f07460b72..d04f3bcaf 100644 --- a/website/sphinx/index.rst +++ b/website/sphinx/index.rst @@ -1,21 +1,131 @@ -Tornado Documentation -===================== +Tornado Web Server +================== + +.. image:: tornado.png + :alt: Tornado Web Server + +`Tornado `_ is an open source version of +the scalable, non-blocking web server and tools that power `FriendFeed +`_. The FriendFeed application is written +using a web framework that looks a bit like `web.py +`_ or `Google's 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 +`_ +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 — 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 +`_.) + +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 `_ for +information about backwards compatibility. + +Quick links +----------- + +* `Documentation `_ +* `Download version |version| `_ (`release notes `_) +* `Source (github) `_ +* `Mailing list `_ +* `Wiki `_ + +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() + +See the `Tornado documentation `_ for a +detailed walkthrough of the framework. + +Installation +------------ + +**Automatic installation:** Tornado is listed in `PyPI +`_ 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 `tornado-|version|.tar.gz `_:: + + 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 +`_. 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 + `_ (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 + `_ 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 + `_ 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 `_. Links +to additional resources can be found on the `Tornado wiki +`_. + +Tornado is one of `Facebook's open source technologies +`_. It is available under +the `Apache License, Version 2.0 +`_. + +This web site and all documentation is licensed under `Creative +Commons 3.0 `_. .. toctree:: - :titlesonly: - - overview - webframework - networking - integration - utilities - releases - - - -Indices and tables -================== + :hidden: + + documentation -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` diff --git a/website/sphinx/tornado.png b/website/sphinx/tornado.png new file mode 100644 index 000000000..a920aa566 Binary files /dev/null and b/website/sphinx/tornado.png differ