docs: break out install_app.py and fix API use.

Author: dw

docs/changelog.rst

@@ -136,6 +136,9 @@ Core Library
   `closed` flag, preventing historical bugs where a double close could destroy
   descriptors belonging to unrelated streams.
 
+* `#606 <https://github.com/dw/mitogen/issues/606>`_: fix example code on the
+  documentation front page.
+
 * `a5536c35 <https://github.com/dw/mitogen/commit/a5536c35>`_: avoid quadratic
   buffer management when logging lines received from a child's redirected
   standard IO.
@@ -150,11 +153,12 @@ bug reports, testing, features and fixes in this release contributed by
 `Anton Markelov <https://github.com/strangeman>`_,
 `Nigel Metheringham <https://github.com/nigelm>`_,
 `Orion Poplawski <https://github.com/opoplawski>`_,
+`Pieter Voet <https://github.com/pietervoet/>`_,
+`Stefane Fermigier <https://github.com/sfermigier>`_,
 `Szabó Dániel Ernő <https://github.com/r3ap3rpy>`_,
 `Ulrich Schreiner <https://github.com/ulrichSchreiner>`_,
 `Yuki Nishida <https://github.com/yuki-nishida-exa>`_,
-`@ghp-rr <https://github.com/ghp-rr>`_,
-`Pieter Voet <https://github.com/pietervoet/>`_, and
+`@ghp-rr <https://github.com/ghp-rr>`_, and
 `@rizzly <https://github.com/rizzly>`_.
 
 

docs/index.rst

@@ -329,36 +329,7 @@ External contexts are configured such that any attempt to execute a function
 from the main Python script will correctly cause that script to be imported as
 usual into the slave process.
 
-.. code-block:: python
-
-    #!/usr/bin/env python
-    """
-    Install our application on a remote machine.
-
-    Usage:
-        install_app.py <hostname>
-
-    Where:
-        <hostname>  Hostname to install to.
-    """
-    import os
-    import sys
-
-    import mitogen
-
-
-    def install_app():
-        os.system('tar zxvf my_app.tar.gz')
-
-
-    @mitogen.main()
-    def main(broker):
-        if len(sys.argv) != 2:
-            print(__doc__)
-            sys.exit(1)
-
-        context = mitogen.ssh.connect(broker, sys.argv[1])
-        context.call(install_app)
+.. literalinclude:: ../examples/install_app.py
 
 
 Event-driven IO

examples/install_app.py

@@ -0,0 +1,28 @@
+#!/usr/bin/env python
+"""
+Install our application on a remote machine.
+
+Usage:
+    install_app.py <hostname>
+
+Where:
+    <hostname>  Hostname to install to.
+"""
+import os
+import sys
+
+import mitogen
+
+
+def install_app():
+    os.system('tar zxvf my_app.tar.gz')
+
+
+@mitogen.main()
+def main(router):
+    if len(sys.argv) != 2:
+        print(__doc__)
+        sys.exit(1)
+
+    context = router.ssh(hostname=sys.argv[1])
+    context.call(install_app)