Add docstring to Controller, explaining dual-stack binding. (#141)

* Add docstring to Controller, explaining how to use it to bind dual-stack (local or all interfaces). Fixes #140.

* Move the documentation to the published docs. For inline docs, reference the published docs.

* Add link to Wikipedia's description of dual-stack for easy context.

* Disable the (broken) IPv6 in Travis. Ref travis-ci/travis-ci#8711

.travis.yml

@@ -9,6 +9,9 @@ matrix:
       env: INTERP=py35 PYTHONASYNCIODEBUG=1
     - python: "3.6"
       env: INTERP=py36 PYTHONASYNCIODEBUG=1
+before_script:
+  # Disable IPv6. Ref travis-ci/travis-ci#8711
+  - echo 0 | sudo tee /proc/sys/net/ipv6/conf/all/disable_ipv6
 script:
   - tox -e $INTERP-nocov,$INTERP-cov,qa,docs
   - 'if [ "$TRAVIS_PULL_REQUEST" != "false" ]; then tox -e $INTERP-diffcov; fi'

aiosmtpd/controller.py

@@ -10,6 +10,11 @@
 class Controller:
     def __init__(self, handler, loop=None, hostname=None, port=8025, *,
                  ready_timeout=1.0, enable_SMTPUTF8=True, ssl_context=None):
+        """
+        `Documentation can be found here
+        <http://aiosmtpd.readthedocs.io/en/latest/aiosmtpd\
+/docs/controller.html#controller-api>`_.
+        """
         self.handler = handler
         self.hostname = '::1' if hostname is None else hostname
         self.port = port

aiosmtpd/docs/controller.rst

@@ -168,7 +168,15 @@ Controller API
    *loop* is the asyncio event loop to use.  If not given,
    :meth:`asyncio.new_event_loop()` is called to create the event loop.
 
-   *hostname* and *port* are passed directly to your loop's
+   *hostname* is passed to your loop's
+   :meth:`AbstractEventLoop.create_server` method as the
+   ``host`` parameter,
+   except None (default) is translated to '::1'. To bind
+   dual-stack locally, use 'localhost'. To bind `dual-stack
+   <https://en.wikipedia.org/wiki/IPv6#Dual-stack_IP_implementation>`_
+   on all interfaces, use ''.
+
+   *port* is passed directly to your loop's
    :meth:`AbstractEventLoop.create_server` method.
 
    *ready_timeout* is float number of seconds that the controller will wait in

examples/server.py

@@ -6,7 +6,7 @@
 
 
 async def amain(loop):
-    cont = Controller(Sink(), hostname='::0', port=8025)
+    cont = Controller(Sink(), hostname='', port=8025)
     cont.start()