Sync documentation

.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: 4a8f705878d9f280d30b6df59cc1f299
+config: f8329b8bbda1a810b9fd3b8f5b12015e
 tags: fbb0d17656682115ca4d033fb2f83ba1

_sources/async/coroutines.txt

@@ -7,44 +7,47 @@
 Coroutines
 ----------
 
-Coroutines are used to break up large and computationally expensive
-tasks into smaller tasks, where control is relinquished to the main
-loop after each smaller task. Coroutines are also very useful in
-constructing state machines. In the event where blocking is
-unavoidable, and the duration of the block is unknown (for example,
-connecting to a remote host, or scaling a very large image), threads
-can be used. These two different approaches are unified with a very
-similar API.
-
-A function or method is designated a coroutine by using the @kaa.coroutine
+Coroutines are special functions that have multiple entry points that allow
+suspending and resuming execution at specified locations.  They allow you to:
+
+ * write sequentially flowing code involving potentially blocking tasks (e.g.
+   socket IO) that is actually completely non-blocking
+ * "time slice" large, computationally expensive tasks to avoid blocking
+ * help solve complex problems involving state `without using explicit state machines <http://eli.thegreenplace.net/2009/08/29/co-routines-as-an-alternative-to-state-machines/>`_
+   the main loop for extended periods without the need for multiple functions
+
+In the event where blocking is unavoidable, and the duration of the block is
+unknown (for example, connecting to a remote host, or scaling a very large
+image), threads can be used.  These two different approaches are unified with a
+very similar API.
+
+A function or method is designated a coroutine by using the ``@kaa.coroutine``
 decorator.  A coroutine allows a larger tasks to be broken down into smaller
 ones by yielding control back to the "scheduler" (the :ref:`notifier
 <notifier>`), implementing a kind of cooperative multitasking.  More usefully,
 coroutines can yield at points where they may otherwise block on resources
 (e.g. disk or network), and when the resource becomes available, the coroutine
-resumes where it left off.  With coroutines and :ref:`InProgress <inprogress>`
-objects, it is possible to construct non-trivial state machines, whose state is
-modified by asynchronous events, using a single coroutine.  Without coroutines,
-this is typically implemented as a series of smaller callback functions.  (For
-more information on coroutines, see `Wikipedia's treatment of the subject
+resumes where it left off.  Without coroutines, this is typically implemented
+as a series of smaller callback functions.  (For more information on
+coroutines, see `Wikipedia's treatment of the subject
 <http://en.wikipedia.org/wiki/Coroutine>`_.)
 
-Any function decorated with coroutine will return an InProgress object, and the
-caller can connect a callback to the InProgress object in order to be notified
-of its return value or any exception.
+Coroutines return an InProgress object, and the caller can connect a callback
+to the InProgress object in order to be notified of its return value or any
+exception, or it can yield the InProgress object from other coroutines.
 
-When a coroutine yields kaa.NotFinished, control is returned to the
+When a coroutine yields ``kaa.NotFinished``, control is returned to the
 main loop, and the coroutine will resume after the yield statement
 at the next main loop iteration, or, if an interval is provided with the
 decorator, after this time interval.  Following the cooperative multitasking
-analogy, yielding kaa.NotFinished can be thought of as the coroutine releasing
+analogy, yielding ``kaa.NotFinished`` can be thought of as the coroutine releasing
 a "time slice" so that other tasks may run.
 
-When a coroutine yields any value other than kaa.NotFinished (including None),
+When a coroutine yields any value other than ``kaa.NotFinished`` (including None),
 the coroutine is considered finished and the InProgress returned to the caller
-will be :ref:`emitted <emitting>` (i.e. it is finished). As with return, if no value is
-explicitly yielded and the coroutine terminates, the InProgress is finished
-with None.
+will be :ref:`emitted <emitting>` (i.e. it is finished). As with return, if no
+value is explicitly yielded and the coroutine terminates, the InProgress is
+finished with None.
 
 There is an important exception to the above rule: if the coroutine yields an
 :class:`~kaa.InProgress` object, the coroutine will be resumed when the
@@ -53,7 +56,7 @@ other InProgress tasks, including other coroutines.
 
 To recap, if a coroutine yields:
 
- * `kaa.NotFinished`: control is returned to the main loop so that other tasks
+ * ``kaa.NotFinished``: control is returned to the main loop so that other tasks
    can run (such as other timers, I/O handlers, etc.) and resumed on the next
    main loop iteration.
  * an :class:`~kaa.InProgress` object: control is returned to the main loop and

_sources/core/signals.txt

@@ -181,7 +181,7 @@ object's :attr:`~kaa.Signal.changed_cb` property (or by passing it on the constr
     ...     if action == kaa.Signal.CONNECTED:
     ...         print 'New callback added, signal now has %d' % len(signal)
     ...     else:
-    ...         print 'Callback added, signal now has %d' % len(signal)
+    ...         print 'Callback removed, signal now has %d' % len(signal)
     ... 
     >>> sig = kaa.Signal(changed_cb=signal_changed)
     >>> callback = sig.connect(lambda: None)

_static/basic.css

@@ -1,6 +1,12 @@
-/**
- * Sphinx stylesheet -- basic theme
- * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+/*
+ * basic.css
+ * ~~~~~~~~~
+ *
+ * Sphinx stylesheet -- basic theme.
+ *
+ * :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
+ * :license: BSD, see LICENSE for details.
+ *
  */
 
 /* -- main layout ----------------------------------------------------------- */
@@ -73,6 +79,14 @@ div.sphinxsidebar input {
     font-size: 1em;
 }
 
+div.sphinxsidebar #searchbox input[type="text"] {
+    width: 170px;
+}
+
+div.sphinxsidebar #searchbox input[type="submit"] {
+    width: 30px;
+}
+
 img {
     border: 0;
 }
@@ -127,6 +141,10 @@ span.linkdescr {
 
 /* -- general index --------------------------------------------------------- */
 
+table.indextable {
+    width: 100%;
+}
+
 table.indextable td {
     text-align: left;
     vertical-align: top;
@@ -152,6 +170,20 @@ img.toggler {
     cursor: pointer;
 }
 
+div.modindex-jumpbox {
+    border-top: 1px solid #ddd;
+    border-bottom: 1px solid #ddd;
+    margin: 1em 0 1em 0;
+    padding: 0.4em;
+}
+
+div.genindex-jumpbox {
+    border-top: 1px solid #ddd;
+    border-bottom: 1px solid #ddd;
+    margin: 1em 0 1em 0;
+    padding: 0.4em;
+}
+
 /* -- general body styles --------------------------------------------------- */
 
 a.headerlink {
@@ -189,6 +221,36 @@ p.rubric {
     font-weight: bold;
 }
 
+img.align-left, .figure.align-left, object.align-left {
+    clear: left;
+    float: left;
+    margin-right: 1em;
+}
+
+img.align-right, .figure.align-right, object.align-right {
+    clear: right;
+    float: right;
+    margin-left: 1em;
+}
+
+img.align-center, .figure.align-center, object.align-center {
+  display: block;
+  margin-left: auto;
+  margin-right: auto;
+}
+
+.align-left {
+    text-align: left;
+}
+
+.align-center {
+    text-align: center;
+}
+
+.align-right {
+    text-align: right;
+}
+
 /* -- sidebars -------------------------------------------------------------- */
 
 div.sidebar {
@@ -252,7 +314,7 @@ table.docutils {
 }
 
 table.docutils td, table.docutils th {
-    padding: 1px 8px 1px 0;
+    padding: 1px 8px 1px 5px;
     border-top: 0;
     border-left: 0;
     border-right: 0;
@@ -272,8 +334,37 @@ th {
     padding-right: 5px;
 }
 
+table.citation {
+    border-left: solid 1px gray;
+    margin-left: 1px;
+}
+
+table.citation td {
+    border-bottom: none;
+}
+
 /* -- other body styles ----------------------------------------------------- */
 
+ol.arabic {
+    list-style: decimal;
+}
+
+ol.loweralpha {
+    list-style: lower-alpha;
+}
+
+ol.upperalpha {
+    list-style: upper-alpha;
+}
+
+ol.lowerroman {
+    list-style: lower-roman;
+}
+
+ol.upperroman {
+    list-style: upper-roman;
+}
+
 dl {
     margin-bottom: 15px;
 }
@@ -292,7 +383,7 @@ dd {
     margin-left: 30px;
 }
 
-dt:target, .highlight {
+dt:target, .highlighted {
     background-color: #fbe54e;
 }
 
@@ -329,7 +420,7 @@ dl.glossary dt {
 }
 
 .footnote:target  {
-    background-color: #ffa
+    background-color: #ffa;
 }
 
 .line-block {
@@ -344,10 +435,28 @@ dl.glossary dt {
     margin-left: 1.5em;
 }
 
+.guilabel, .menuselection {
+    font-family: sans-serif;
+}
+
+.accelerator {
+    text-decoration: underline;
+}
+
+.classifier {
+    font-style: oblique;
+}
+
+abbr, acronym {
+    border-bottom: dotted 1px;
+    cursor: help;
+}
+
 /* -- code displays --------------------------------------------------------- */
 
 pre {
     overflow: auto;
+    overflow-y: hidden;  /* fixes display issues on Chrome browsers */
 }
 
 td.linenos pre {
@@ -384,6 +493,20 @@ h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
     background-color: transparent;
 }
 
+.viewcode-link {
+    float: right;
+}
+
+.viewcode-back {
+    float: right;
+    font-family: sans-serif;
+}
+
+div.viewcode-block:target {
+    margin: -1px -10px;
+    padding: 0 10px;
+}
+
 /* -- math display ---------------------------------------------------------- */
 
 img.math {
@@ -414,4 +537,4 @@ span.eqno {
     #top-link {
         display: none;
     }
-}
+}