Permalink
Browse files

More documentation.

  • Loading branch information...
1 parent 8252c3b commit 5f53a22b1a6ee17b79521aea090c7943171f6689 @mrjoes committed Nov 1, 2011
Showing with 555 additions and 14 deletions.
  1. +4 −0 .gitignore
  2. +153 −0 Makefile
  3. +15 −3 README.rst
  4. +246 −0 doc/conf.py
  5. +30 −0 doc/index.rst
  6. +7 −0 tornadio2/conn.py
  7. +3 −0 tornadio2/periodic.py
  8. +10 −8 tornadio2/persistent.py
  9. +12 −1 tornadio2/polling.py
  10. +75 −2 tornadio2/proto.py
View
@@ -4,3 +4,7 @@
*.*~
pyenv
#*#
+build
+source/_static*
+source/_templates*
+make.bat
View
153 Makefile
@@ -0,0 +1,153 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS =
+SPHINXBUILD = sphinx-build
+PAPER =
+BUILDDIR = build
+
+# Internal variables.
+PAPEROPT_a4 = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+
+help:
+ @echo "Please use \`make <target>' where <target> is one of"
+ @echo " html to make standalone HTML files"
+ @echo " dirhtml to make HTML files named index.html in directories"
+ @echo " singlehtml to make a single large HTML file"
+ @echo " pickle to make pickle files"
+ @echo " json to make JSON files"
+ @echo " htmlhelp to make HTML files and a HTML help project"
+ @echo " qthelp to make HTML files and a qthelp project"
+ @echo " devhelp to make HTML files and a Devhelp project"
+ @echo " epub to make an epub"
+ @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+ @echo " latexpdf to make LaTeX files and run them through pdflatex"
+ @echo " text to make text files"
+ @echo " man to make manual pages"
+ @echo " texinfo to make Texinfo files"
+ @echo " info to make Texinfo files and run them through makeinfo"
+ @echo " gettext to make PO message catalogs"
+ @echo " changes to make an overview of all changed/added/deprecated items"
+ @echo " linkcheck to check all external links for integrity"
+ @echo " doctest to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+ -rm -rf $(BUILDDIR)/*
+
+html:
+ $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+ @echo
+ @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+ $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+ @echo
+ @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+ $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+ @echo
+ @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+ $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+ @echo
+ @echo "Build finished; now you can process the pickle files."
+
+json:
+ $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+ @echo
+ @echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+ $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+ @echo
+ @echo "Build finished; now you can run HTML Help Workshop with the" \
+ ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+ $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+ @echo
+ @echo "Build finished; now you can run "qcollectiongenerator" with the" \
+ ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+ @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/TornadIO2.qhcp"
+ @echo "To view the help file:"
+ @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/TornadIO2.qhc"
+
+devhelp:
+ $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+ @echo
+ @echo "Build finished."
+ @echo "To view the help file:"
+ @echo "# mkdir -p $$HOME/.local/share/devhelp/TornadIO2"
+ @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/TornadIO2"
+ @echo "# devhelp"
+
+epub:
+ $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+ @echo
+ @echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo
+ @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+ @echo "Run \`make' in that directory to run these through (pdf)latex" \
+ "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo "Running LaTeX files through pdflatex..."
+ $(MAKE) -C $(BUILDDIR)/latex all-pdf
+ @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+ $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+ @echo
+ @echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+ $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+ @echo
+ @echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+texinfo:
+ $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+ @echo
+ @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+ @echo "Run \`make' in that directory to run these through makeinfo" \
+ "(use \`make info' here to do that automatically)."
+
+info:
+ $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+ @echo "Running Texinfo files through makeinfo..."
+ make -C $(BUILDDIR)/texinfo info
+ @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+gettext:
+ $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+ @echo
+ @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+changes:
+ $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+ @echo
+ @echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+ $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+ @echo
+ @echo "Link check complete; look for any errors in the above output " \
+ "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+ $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+ @echo "Testing of doctests in the sources finished, look at the " \
+ "results in $(BUILDDIR)/doctest/output.txt."
View
@@ -2,8 +2,6 @@
TornadIO2
=========
-.WIP.
-
Contributors
------------
@@ -20,7 +18,7 @@ most of the features found in original Socket.IO server software.
Getting Started
---------------
-In order to start working with the TornadIO2 library, you need to know some basic Tornado
+In order to start working with the TornadIO2 library, you have to have some basic Tornado
knowledge. If you don't know how to use it, please read Tornado tutorial, which can be found
`here <http://www.tornadoweb.org/documentation#tornado-walk-through>`_.
@@ -60,6 +58,7 @@ routing mechanism or implement your own.
To use built-in routing, declare and initialize `__endpoints__` dictionary in
your main connection class:
::
+
class ChatConnection(SocketConnection):
def on_message(self, msg):
pass
@@ -79,6 +78,7 @@ your main connection class:
On client side, create two connections:
::
+
var chat = io.connect('http://myserver/chat'),
ping = io.connect('http://myserver/ping');
@@ -89,6 +89,7 @@ So, you have to have three connection classes for 2 virtual connections - that's
socket.io works. If you want, you can send some messages to MyRouterConnection as well,
if you will connect like this:
::
+
var conn = io.connect('http://myserver'),
chat = io.connect('http://myserver/chat'),
ping = io.connect('http://myserver/ping');
@@ -103,6 +104,7 @@ New feature of the socket.io 0.7+. When you send message to the client,
you now have way to get notified when client receives the message. To use this, pass a
callback function when sending a message:
::
+
class MyConnection(SocketConnection):
def on_message(self, msg):
self.send(msg, self.my_callback)
@@ -120,6 +122,7 @@ Event is just a name and collection of parameters.
TornadIO2 provides easy-to-use syntax sugar which emulates RPC calls from the client
to your python code. Check following example:
::
+
class MyConnection(SocketConnection):
@event('hello')
def test(self, name):
@@ -129,6 +132,7 @@ to your python code. Check following example:
In your client code, to call this event, do something like:
::
+
sock.emit('hello', {name: 'Joes'});
However, take care - if method signature does not match (missing parameters, extra
@@ -137,6 +141,7 @@ parameters, etc), your connection will blow up and self destruct.
If you don't like this event handling approach, just override `on_event` in your
socket connection class and handle them by yourself:
::
+
class MyConnection(SocketConnection):
def on_event(self, name, *args, **kwargs):
if name == 'hello':
@@ -149,6 +154,7 @@ with events.
If you send data from client using following code:
::
+
sock.emit('test', {a: 10, b: 10});
@@ -157,6 +163,7 @@ TornadIO2 will unpack dictionary into `kwargs` parameters and pass it to the
unpack them into `kwargs` and will just pass parameters as `args`. For example, this
code will lead to `args` being passed to `on_event` handler:
::
+
sock.emit('test', 1, 2, 3, {a: 10, b: 10});
@@ -214,6 +221,7 @@ This change affected how TornadIO2 is initialized and plugged into your Tornado
or alternative approach:
::
+
ChatServer = tornadio2.router.TornadioServer(ChatConnection)
application = tornado.web.Application(ChatServer.apply_routes([(r"/", IndexHandler)]))
@@ -224,6 +232,7 @@ TornadIO2 will reject connection.
Example:
::
+
class MyConnection(SocketConnection):
def on_open(self, request):
self.user_id = request.get_argument('id')
@@ -256,9 +265,12 @@ associated socket, you will end up having your callbacks called twice, etc.
For now, if your main connection was closed, you have two options:
::
+
var conn = io.connect(addr, {'force new connection': true});
+
or alternative approach:
::
+
io.j = [];
io.sockets = [];
Oops, something went wrong.

0 comments on commit 5f53a22

Please sign in to comment.