Add documentation

10 files changed, 1733 insertions, 0 deletions

diff --git a/doc/Makefile b/doc/Makefile
new file mode 100644
index 0000000..314751a
--- /dev/null
+++ b/doc/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) .
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.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/Trollius.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Trollius.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/Trollius"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Trollius"
+	@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."
diff --git a/doc/asyncio.rst b/doc/asyncio.rst
new file mode 100644
index 0000000..5866d62
--- /dev/null
+++ b/doc/asyncio.rst
@@ -0,0 +1,185 @@
+++++++++++++++++++
+Trollius and Tulip
+++++++++++++++++++
+
+Differences between Trollius and Tulip
+======================================
+
+Syntax of coroutines
+--------------------
+
+The major difference between Trollius and Tulip is the syntax of coroutines:
+
+==================  ======================
+Tulip               Trollius
+==================  ======================
+``yield from ...``  ``yield From(...)``
+``yield from []``   ``yield From(None)``
+``return``          ``raise Return()``
+``return x``        ``raise Return(x)``
+``return x, y``     ``raise Return(x, y)``
+==================  ======================
+
+Because of this major difference, it was decided to call the module
+``trollius`` instead of ``asyncio``. This choice also allows to use Trollius on
+Python 3.4 and later. Changing imports is not enough to use Trollius code with
+asyncio: the asyncio event loop explicit rejects coroutines using ``yield``
+(instead of ``yield from``).
+
+OSError and socket.error exceptions
+-----------------------------------
+
+The ``OSError`` exception changed in Python 3.3: there are now subclasses like
+``ConnectionResetError`` or ``BlockingIOError``. The exception hierarchy also
+changed: ``socket.error`` is now an alias to ``OSError``. The ``asyncio``
+module is written for Python 3.3 and newer and so is based on these new
+exceptions.
+
+.. seealso::
+
+   `PEP 3151: Reworking the OS and IO exception hierarchy
+   <https://www.python.org/dev/peps/pep-3151>`_.
+
+On Python 3.2 and older, Trollius wraps ``OSError``, ``IOError``,
+``socket.error`` and ``select.error`` exceptions on operating system and socket
+operations to raise more specific exceptions, subclasses of ``OSError``:
+
+* ``trollius.BlockingIOError``
+* ``trollius.BrokenPipeError``
+* ``trollius.ChildProcessError``
+* ``trollius.ConnectionAbortedError``
+* ``trollius.ConnectionRefusedError``
+* ``trollius.ConnectionResetError``
+* ``trollius.FileNotFoundError``
+* ``trollius.InterruptedError``
+* ``trollius.PermissionError``
+
+On Python 3.3 and newer, these symbols are just aliases to builtin exceptions.
+
+.. note::
+
+   ``ssl.SSLError`` exceptions are not wrapped to ``OSError``, even if
+   ``ssl.SSLError`` is a subclass of ``socket.error``.
+
+
+SSLError
+--------
+
+On Python 3.2 and older, Trollius wraps ``ssl.SSLError`` exceptions to raise
+more specific exceptions, subclasses of ``ssl.SSLError``, to mimic the Python
+3.3:
+
+* ``trollius.SSLEOFError``
+* ``trollius.SSLWantReadError``
+* ``trollius.SSLWantWriteError``
+
+On Python 3.3 and newer, these symbols are just aliases to exceptions of the
+``ssl`` module.
+
+``trollius.BACKPORT_SSL_ERRORS`` constant:
+
+* ``True`` if ``ssl.SSLError`` are wrapped to Trollius exceptions (Python 2
+  older than 2.7.9, or Python 3 older than 3.3),
+* ``False`` is trollius SSL exceptions are just aliases.
+
+
+SSLContext
+----------
+
+Python 3.3 has a new ``ssl.SSLContext`` class: see the `documentaton of the
+ssl.SSLContext class
+<https://docs.python.org/3/library/ssl.html#ssl.SSLContext>`_.
+
+On Python 3.2 and older, Trollius has a basic ``trollius.SSLContext`` class to
+mimic Python 3.3 API, but it only has a few features:
+
+* ``protocol``, ``certfile`` and ``keyfile`` attributes
+* read-only ``verify_mode`` attribute: its value is ``CERT_NONE``
+* ``load_cert_chain(certfile, keyfile)`` method
+* ``wrap_socket(sock, **kw)`` method: see the ``ssl.wrap_socket()``
+  documentation of your Python version for the keyword parameters
+
+Example of missing features:
+
+* no ``options`` attribute
+* the ``verify_mode`` attriubte cannot be modified
+* no ``set_default_verify_paths()`` method
+* no "Server Name Indication" (SNI) support
+* etc.
+
+On Python 3.2 and older, the trollius SSL transport does not have the
+``'compression'`` extra info.
+
+``trollius.BACKPORT_SSL_CONTEXT`` constant:
+
+* ``True`` if ``trollius.SSLContext`` is the backported class (Python 2 older
+  than 2.7.9, or Python 3 older than 3.3),
+* ``False`` if ``trollius.SSLContext`` is just an alias to ``ssl.SSLContext``.
+
+
+Other differences
+-----------------
+
+* Trollius uses the ``TROLLIUSDEBUG`` envrionment variable instead of
+  the ``PYTHONASYNCIODEBUG`` envrionment variable. ``TROLLIUSDEBUG`` variable
+  is used even if the Python command line option ``-E`` is used.
+* ``asyncio.subprocess`` has no ``DEVNULL`` constant
+* Python 2 does not support keyword-only parameters.
+* If the ``concurrent.futures`` module is missing,
+  ``BaseEventLoop.run_in_executor()`` uses a synchronous executor instead of a
+  pool of threads. It blocks until the function returns. For example, DNS
+  resolutions are blocking in this case.
+* Trollius has more symbols than Tulip for compatibility with Python older than
+  3.3:
+
+  - ``From``: part of ``yield From(...)`` syntax
+  - ``Return``: part of ``raise Return(...)`` syntax
+
+
+Write code working on Trollius and Tulip
+========================================
+
+Trollius and Tulip are different, especially for coroutines (``yield
+From(...)`` vs ``yield from ...``).
+
+To use asyncio or Trollius on Python 2 and Python 3, add the following code at
+the top of your file::
+
+    try:
+        # Use builtin asyncio on Python 3.4+, or Tulip on Python 3.3
+        import asyncio
+    except ImportError:
+        # Use Trollius on Python <= 3.2
+        import trollius as asyncio
+
+It is possible to write code working on both projects using only callbacks.
+This option is used by the following projects which work on Trollius and Tulip:
+
+* `AutobahnPython <https://github.com/tavendo/AutobahnPython>`_: WebSocket &
+  WAMP for Python, it works on Trollius (Python 2.6 and 2.7), Tulip (Python
+  3.3) and Python 3.4 (asyncio), and also on Twisted.
+* `Pulsar <http://pythonhosted.org/pulsar/>`_: Event driven concurrent
+  framework for Python. With pulsar you can write asynchronous servers
+  performing one or several activities in different threads and/or processes.
+  Trollius 0.3 requires Pulsar 0.8.2 or later. Pulsar uses the ``asyncio``
+  module if available, or import ``trollius``.
+* `Tornado <http://www.tornadoweb.org/>`_ supports Tulip and Trollius since
+  Tornado 3.2: `tornado.platform.asyncio — Bridge between asyncio and Tornado
+  <http://tornado.readthedocs.org/en/latest/asyncio.html>`_. It tries to import
+  asyncio or fallback on importing trollius.
+
+Another option is to provide functions returning ``Future`` objects, so the
+caller can decide to use callback using ``fut.add_done_callback(callback)`` or
+to use coroutines (``yield From(fut)`` for Trollius, or ``yield from fut`` for
+Tulip). This option is used by the `aiodns <https://github.com/saghul/aiodns>`_
+project for example.
+
+Since Trollius 0.4, it's possible to use Tulip and Trollius coroutines in the
+same process. The only limit is that the event loop must be a Trollius event
+loop.
+
+.. note::
+
+   The Trollius module was called ``asyncio`` in Trollius version 0.2. The
+   module name changed to ``trollius`` to support Python 3.4.
+
diff --git a/doc/changelog.rst b/doc/changelog.rst
new file mode 100644
index 0000000..1ddfc21
--- /dev/null
+++ b/doc/changelog.rst
@@ -0,0 +1,604 @@
+++++++++++
+Change log
+++++++++++
+
+Version 1.0.5
+=============
+
+Major changes: on Python 3.5+ ProactorEventLoop now supports SSL, a lot of
+bugfixes (random race conditions) in the ProactorEventLoop.
+
+API changes:
+
+* Python issue #23209, #23225: selectors.BaseSelector.get_key() now raises a
+  RuntimeError if the selector is closed. And selectors.BaseSelector.close()
+  now clears its internal reference to the selector mapping to break a
+  reference cycle. Initial patch written by Martin Richard.
+* PipeHandle.fileno() of asyncio.windows_utils now raises an exception if the
+  pipe is closed.
+* Remove Overlapped.WaitNamedPipeAndConnect() of the _overlapped module,
+  it is no more used and it had issues.
+
+New SSL implementation:
+
+* Python issue #22560: On Python 3.5 and newer, a new SSL implementation based
+  on ssl.MemoryBIO instead of the legacy SSL implementation. Patch written by
+  Antoine Pitrou, based on the work of Geert Jansen.
+* If available, the new SSL implementation can be used by ProactorEventLoop to
+  support SSL.
+
+Enhance, fix and cleanup the IocpProactor:
+
+* Python issue #23293: Rewrite IocpProactor.connect_pipe(). Add
+  _overlapped.ConnectPipe() which tries to connect to the pipe for asynchronous
+  I/O (overlapped): call CreateFile() in a loop until it doesn't fail with
+  ERROR_PIPE_BUSY. Use an increasing delay between 1 ms and 100 ms.
+* Tulip issue #204: Fix IocpProactor.accept_pipe().
+  Overlapped.ConnectNamedPipe() now returns a boolean: True if the pipe is
+  connected (if ConnectNamedPipe() failed with ERROR_PIPE_CONNECTED), False if
+  the connection is in progress.
+* Tulip issue #204: Fix IocpProactor.recv(). If ReadFile() fails with
+  ERROR_BROKEN_PIPE, the operation is not pending: don't register the
+  overlapped.
+* Python issue #23095: Rewrite _WaitHandleFuture.cancel().
+  _WaitHandleFuture.cancel() now waits until the wait is cancelled to clear its
+  reference to the overlapped object. To wait until the cancellation is done,
+  UnregisterWaitEx() is used with an event instead of UnregisterWait().
+* Python issue #23293: Rewrite IocpProactor.connect_pipe() as a coroutine. Use
+  a coroutine with asyncio.sleep() instead of call_later() to ensure that the
+  schedule call is cancelled.
+* Fix ProactorEventLoop.start_serving_pipe(). If a client connected before the
+  server was closed: drop the client (close the pipe) and exit
+* Python issue #23293: Cleanup IocpProactor.close(). The special case for
+  connect_pipe() is not more needed. connect_pipe() doesn't use overlapped
+  operations anymore.
+*  IocpProactor.close(): don't cancel futures which are already cancelled
+* Enhance (fix) BaseProactorEventLoop._loop_self_reading(). Handle correctly
+  CancelledError: just exit. On error, log the exception and exit; don't try to
+  close the event loop (it doesn't work).
+
+Bugfixes:
+
+* Close transports on error. Fix create_datagram_endpoint(),
+  connect_read_pipe() and connect_write_pipe(): close the transport if the task
+  is cancelled or on error.
+* Close the transport on subprocess creation failure
+* Fix _ProactorBasePipeTransport.close(). Set the _read_fut attribute to None
+  after cancelling it.
+* Python issue #23243: Fix _UnixWritePipeTransport.close(). Do nothing if the
+  transport is already closed. Before it was not possible to close the
+  transport twice.
+* Python issue #23242: SubprocessStreamProtocol now closes the subprocess
+  transport at subprocess exit. Clear also its reference to the transport.
+* Fix BaseEventLoop._create_connection_transport(). Close the transport if the
+  creation of the transport (if the waiter) gets an exception.
+* Python issue #23197: On SSL handshake failure, check if the waiter is
+  cancelled before setting its exception.
+* Python issue #23173: Fix SubprocessStreamProtocol.connection_made() to handle
+  cancelled waiter.
+* Python issue #23173: If an exception is raised during the creation of a
+  subprocess, kill the subprocess (close pipes, kill and read the return
+  status). Log an error in such case.
+* Python issue #23209: Break some reference cycles in asyncio. Patch written by
+  Martin Richard.
+
+Changes:
+
+* Python issue #23208: Add BaseEventLoop._current_handle. In debug mode,
+  BaseEventLoop._run_once() now sets the BaseEventLoop._current_handle
+  attribute to the handle currently executed.
+* Replace test_selectors.py with the file of Python 3.5 adapted for asyncio and
+  Python 3.3.
+* Tulip issue #184: FlowControlMixin constructor now get the event loop if the
+  loop parameter is not set.
+* _ProactorBasePipeTransport now sets the _sock attribute to None when the
+  transport is closed.
+* Python issue #23219: cancelling wait_for() now cancels the task
+* Python issue #23243: Close explicitly event loops and transports in tests
+* Python issue #23140: Fix cancellation of Process.wait(). Check the state of
+  the waiter future before setting its result.
+* Python issue #23046: Expose the BaseEventLoop class in the asyncio namespace
+* Python issue #22926: In debug mode, call_soon(), call_at() and call_later()
+  methods of BaseEventLoop now use the identifier of the current thread to
+  ensure that they are called from the thread running the event loop. Before,
+  the get_event_loop() method was used to check the thread, and no exception
+  was raised when the thread had no event loop. Now the methods always raise an
+  exception in debug mode when called from the wrong thread. It should help to
+  notice misusage of the API.
+
+
+2014-12-19: Version 1.0.4
+=========================
+
+Changes:
+
+* Python issue #22922: create_task(), call_at(), call_soon(),
+  call_soon_threadsafe() and run_in_executor() now raise an error if the event
+  loop is closed. Initial patch written by Torsten Landschoff.
+* Python issue #22921: Don't require OpenSSL SNI to pass hostname to ssl
+  functions. Patch by Donald Stufft.
+* Add run_aiotest.py: run the aiotest test suite.
+* tox now also run the aiotest test suite
+* Python issue #23074: get_event_loop() now raises an exception if the thread
+  has no event loop even if assertions are disabled.
+
+Bugfixes:
+
+* Fix a race condition in BaseSubprocessTransport._try_finish(): ensure that
+  connection_made() is called before connection_lost().
+* Python issue #23009: selectors, make sure EpollSelecrtor.select() works when
+  no file descriptor is registered.
+* Python issue #22922: Fix ProactorEventLoop.close(). Call
+  _stop_accept_futures() before sestting the _closed attribute, otherwise
+  call_soon() raises an error.
+* Python issue #22429: Fix EventLoop.run_until_complete(), don't stop the event
+  loop if a BaseException is raised, because the event loop is already stopped.
+* Initialize more Future and Task attributes in the class definition to avoid
+  attribute errors in destructors.
+* Python issue #22685: Set the transport of stdout and stderr StreamReader
+  objects in the SubprocessStreamProtocol. It allows to pause the transport to
+  not buffer too much stdout or stderr data.
+* BaseSelectorEventLoop.close() now closes the self-pipe before calling the
+  parent close() method. If the event loop is already closed, the self-pipe is
+  not unregistered from the selector.
+
+
+2014-10-20: Version 1.0.3
+=========================
+
+Changes:
+
+* On Python 2 in debug mode, Future.set_exception() now stores the traceback
+  object of the exception in addition to the exception object. When a task
+  waiting for another task and the other task raises an exception, the
+  traceback object is now copied with the exception. Be careful, storing the
+  traceback object may create reference leaks.
+* Use ssl.create_default_context() if available to create the default SSL
+  context: Python 2.7.9 and newer, or Python 3.4 and newer.
+* On Python 3.5 and newer, reuse socket.socketpair() in the windows_utils
+  submodule.
+* On Python 3.4 and newer, use os.set_inheritable().
+* Enhance protocol representation: add "closed" or "closing" info.
+* run_forever() now consumes BaseException of the temporary task. If the
+  coroutine raised a BaseException, consume the exception to not log a warning.
+  The caller doesn't have access to the local task.
+* Python issue 22448: cleanup _run_once(), only iterate once to remove delayed
+  calls that were cancelled.
+* The destructor of the Return class now shows where the Return object was
+  created.
+* run_tests.py doesn't catch any exceptions anymore when loading tests, only
+  catch SkipTest.
+* Fix (SSL) tests for the future Python 2.7.9 which includes a "new" ssl
+  module: module backported from Python 3.5.
+* BaseEventLoop.add_signal_handler() now raises an exception if the parameter
+  is a coroutine function.
+* Coroutine functions and objects are now rejected with a TypeError by the
+  following functions: add_signal_handler(), call_at(), call_later(),
+  call_soon(), call_soon_threadsafe(), run_in_executor().
+
+
+2014-10-02: Version 1.0.2
+=========================
+
+This release fixes bugs. It also provides more information in debug mode on
+error.
+
+Major changes:
+
+* Tulip issue #203: Add _FlowControlMixin.get_write_buffer_limits() method.
+* Python issue #22063: socket operations (socket,recv, sock_sendall,
+  sock_connect, sock_accept) of SelectorEventLoop now raise an exception in
+  debug mode if sockets are in blocking mode.
+
+Major bugfixes:
+
+* Tulip issue #205: Fix a race condition in BaseSelectorEventLoop.sock_connect().
+* Tulip issue #201: Fix a race condition in wait_for(). Don't raise a
+  TimeoutError if we reached the timeout and the future completed in the same
+  iteration of the event loop. A side effect of the bug is that Queue.get()
+  looses items.
+* PipeServer.close() now cancels the "accept pipe" future which cancels the
+  overlapped operation.
+
+Other changes:
+
+* Python issue #22448: Improve cancelled timer callback handles cleanup. Patch
+  by Joshua Moore-Oliva.
+* Python issue #22369: Change "context manager protocol" to "context management
+  protocol". Patch written by Serhiy Storchaka.
+* Tulip issue #206: In debug mode, keep the callback in the representation of
+  Handle and TimerHandle after cancel().
+* Tulip issue #207: Fix test_tasks.test_env_var_debug() to use correct asyncio
+  module.
+* runtests.py: display a message to mention if tests are run in debug or
+  release mode
+* Tulip issue #200: Log errors in debug mode instead of simply ignoring them.
+* Tulip issue #200: _WaitHandleFuture._unregister_wait() now catchs and logs
+  exceptions.
+* _fatal_error() method of _UnixReadPipeTransport and _UnixWritePipeTransport
+  now log all exceptions in debug mode
+* Fix debug log in BaseEventLoop.create_connection(): get the socket object
+  from the transport because SSL transport closes the old socket and creates a
+  new SSL socket object.
+* Remove the _SelectorSslTransport._rawsock attribute: it contained the closed
+  socket (not very useful) and it was not used.
+* Fix _SelectorTransport.__repr__() if the transport was closed
+* Use the new os.set_blocking() function of Python 3.5 if available
+
+
+2014-07-30: Version 1.0.1
+=========================
+
+This release supports PyPy and has a better support of asyncio coroutines,
+especially in debug mode.
+
+Changes:
+
+* Tulip issue #198: asyncio.Condition now accepts an optional lock object.
+* Enhance representation of Future and Future subclasses: add "created at".
+
+Bugfixes:
+
+* Fix Trollius issue #9: @trollius.coroutine now works on callbable objects
+  (without ``__name__`` attribute), not only on functions.
+* Fix Trollius issue #13: asyncio futures are now accepted in all functions:
+  as_completed(), async(), @coroutine, gather(), run_until_complete(),
+  wrap_future().
+* Fix support of asyncio coroutines in debug mode. If the last instruction
+  of the coroutine is "yield from", it's an asyncio coroutine and it does not
+  need to use From().
+* Fix and enhance _WaitHandleFuture.cancel():
+
+  - Tulip issue #195: Fix a crash on Windows: don't call UnregisterWait() twice
+    if a _WaitHandleFuture is cancelled twice.
+  - Fix _WaitHandleFuture.cancel(): return the result of the parent cancel()
+    method (True or False).
+  - _WaitHandleFuture.cancel() now notify IocpProactor through the overlapped
+    object that the wait was cancelled.
+
+* Tulip issue #196: _OverlappedFuture now clears its reference to the
+  overlapped object. IocpProactor keeps a reference to the overlapped object
+  until it is notified of its completion. Log also an error in debug mode if it
+  gets unexpected notifications.
+* Fix runtest.py to be able to log at level DEBUG.
+
+Other changes:
+
+* BaseSelectorEventLoop._write_to_self() now logs errors in debug mode.
+* Fix as_completed(): it's not a coroutine, don't use ``yield From(...)`` but
+  ``yield ...``
+* Tulip issue #193: Convert StreamWriter.drain() to a classic coroutine.
+* Tulip issue #194: Don't use sys.getrefcount() in unit tests: the full test
+  suite now pass on PyPy.
+
+
+2014-07-21: Version 1.0
+=======================
+
+Major Changes
+-------------
+
+* Event loops have a new ``create_task()`` method, which is now the recommanded
+  way to create a task object. This method can be overriden by third-party
+  event loops to use their own task class.
+* The debug mode has been improved a lot. Set ``TROLLIUSDEBUG`` envrironment
+  variable to ``1`` and configure logging to log at level ``logging.DEBUG``
+  (ex: ``logging.basicConfig(level=logging.DEBUG)``).  Changes:
+
+  - much better representation of Trollius objects (ex: ``repr(task)``):
+    unified ``<Class arg1 arg2 ...>`` format, use qualified name when available
+  - show the traceback where objects were created
+  - show the current filename and line number for coroutine
+  - show the filename and line number where objects were created
+  - log most important socket events
+  - log most important subprocess events
+
+* ``Handle.cancel()`` now clears references to callback and args
+* Log an error if a Task is destroyed while it is still pending, but only on
+  Python 3.4 and newer.
+* Fix for asyncio coroutines when passing tuple value in debug mode.
+  ``CoroWrapper.send()`` now checks if it is called from a "yield from"
+  generator to decide if the parameter should be unpacked or not.
+* ``Process.communicate()`` now ignores ``BrokenPipeError`` and
+  ``ConnectionResetError`` exceptions.
+* Rewrite signal handling on Python 3.3 and newer to fix a race condition: use
+  the "self-pipe" to get signal numbers.
+
+
+Other Changes
+-------------
+
+* Fix ``ProactorEventLoop()`` in debug mode
+* Fix a race condition when setting the result of a Future with
+  ``call_soon()``. Add an helper, a private method, to set the result only if
+  the future was not cancelled.
+* Fix ``asyncio.__all__``: export also ``unix_events`` and ``windows_events``
+  symbols. For example, on Windows, it was not possible to get
+  ``ProactorEventLoop`` or ``DefaultEventLoopPolicy`` using ``from asyncio
+  import *``.
+* ``Handle.cancel()`` now clears references to callback and args
+* Make Server attributes and methods private, the sockets attribute remains
+  public.
+* BaseEventLoop.create_datagram_endpoint() now waits until
+  protocol.connection_made() has been called. Document also why transport
+  constructors use a waiter.
+* _UnixSubprocessTransport: fix file mode of stdin: open stdin in write mode,
+  not in read mode.
+
+
+2014-06-23: version 0.4
+=======================
+
+Changes between Trollius 0.3 and 0.4:
+
+* Trollius event loop now supports asyncio coroutines:
+
+  - Trollius coroutines can yield asyncio coroutines,
+  - asyncio coroutines can yield Trollius coroutines,
+  - asyncio.set_event_loop() accepts a Trollius event loop,
+  - asyncio.set_event_loop_policy() accepts a Trollius event loop policy.
+
+* The ``PYTHONASYNCIODEBUG`` envrionment variable has been renamed to
+  ``TROLLIUSDEBUG``. The environment variable is now used even if the Python
+  command line option ``-E`` is used.
+* Synchronize with Tulip.
+* Support PyPy (fix subproces, fix unit tests).
+
+Tulip changes:
+
+* Tulip issue #171: BaseEventLoop.close() now raises an exception if the event
+  loop is running. You must first stop the event loop and then wait until it
+  stopped, before closing it.
+* Tulip issue #172: only log selector timing in debug mode
+* Enable the debug mode of event loops when the ``TROLLIUSDEBUG`` environment
+  variable is set
+* BaseEventLoop._assert_is_current_event_loop() now only raises an exception if
+  the current loop is set.
+* Tulip issue #105: in debug mode, log callbacks taking more than 100 ms to be
+  executed.
+* Python issue 21595: ``BaseSelectorEventLoop._read_from_self()`` reads all
+  available bytes from the "self pipe", not only a single byte. This change
+  reduces the risk of having the pipe full and so getting the "BlockingIOError:
+  [Errno 11] Resource temporarily unavailable" message.
+* Python issue 21723: asyncio.Queue: support any type of number (ex: float) for
+  the maximum size. Patch written by Vajrasky Kok.
+* Issue #173: Enhance repr(Handle) and repr(Task): add the filename and line
+  number, when available. For task, the current line number of the coroutine
+  is used.
+* Add BaseEventLoop.is_closed() method. run_forever() and run_until_complete()
+  methods now raises an exception if the event loop was closed.
+* Make sure that socketpair() close sockets on error. Close the listening
+  socket if sock.bind() raises an exception.
+* Fix ResourceWarning: close sockets on errors.
+  BaseEventLoop.create_connection(), BaseEventLoop.create_datagram_endpoint()
+  and _UnixSelectorEventLoop.create_unix_server() now close the newly created
+  socket on error.
+* Rephrase and fix docstrings.
+* Fix tests on Windows: wait for the subprocess exit. Before, regrtest failed
+  to remove the temporary test directory because the process was still running
+  in this directory.
+* Refactor unit tests.
+
+On Python 3.5, generators now get their name from the function, no more from
+the code. So the ``@coroutine`` decorator doesn't loose the original name of
+the function anymore.
+
+
+2014-05-26: version 0.3
+=======================
+
+Rename the Python module ``asyncio`` to ``trollius`` to support Python 3.4. On
+Python 3.4, there is already a module called ``asyncio`` in the standard
+library which conflicted with ``asyncio`` module of Trollius 0.2. To write
+asyncio code working on Trollius and Tulip, use ``import trollius as asyncio``.
+
+Changes between Trollius 0.2 and 0.3:
+
+* Synchronize with Tulip 3.4.1.
+* Enhance Trollius documentation.
+* Trollius issue #7: Fix ``asyncio.time_monotonic`` on Windows older than
+  Vista (ex: Windows 2000 and Windows XP).
+* Fedora packages have been accepted.
+
+Changes between Tulip 3.4.0 and 3.4.1:
+
+* Pull in Solaris ``devpoll`` support by Giampaolo Rodola
+  (``trollius.selectors`` module).
+* Add options ``-r`` and ``--randomize`` to runtests.py to randomize test
+  order.
+* Add a simple echo client/server example.
+* Tulip issue #166: Add ``__weakref__`` slots to ``Handle`` and
+  ``CoroWrapper``.
+* ``EventLoop.create_unix_server()`` now raises a ``ValueError`` if path and
+  sock are specified at the same time.
+* Ensure ``call_soon()``, ``call_later()`` and ``call_at()`` are invoked on
+  current loop in debug mode. Raise a ``RuntimeError`` if the event loop of the
+  current thread is different.  The check should help to debug thread-safetly
+  issue. Patch written by David Foster.
+* Tulip issue #157: Improve test_events.py, avoid ``run_briefly()`` which is
+  not reliable.
+* Reject add/remove reader/writer when event loop is closed.
+
+Bugfixes of Tulip 3.4.1:
+
+* Tulip issue #168: ``StreamReader.read(-1)`` from pipe may hang if
+  data exceeds buffer limit.
+* CPython issue #21447: Fix a race condition in
+  ``BaseEventLoop._write_to_self()``.
+* Different bugfixes in ``CoroWrapper`` of ``trollius.coroutines``, class used
+  when running Trollius in debug mode:
+
+  - Fix ``CoroWrapper`` to workaround yield-from bug in CPython 3.4.0. The
+    CPython bug is now fixed in CPython 3.4.1 and 3.5.
+  - Make sure ``CoroWrapper.send`` proxies one argument correctly.
+  - CPython issue #21340: Be careful accessing instance variables in ``__del__``.
+  - Tulip issue #163: Add ``gi_{frame,running,code}`` properties to
+    ``CoroWrapper``.
+
+* Fix ``ResourceWarning`` warnings
+* Tulip issue #159: Fix ``windows_utils.socketpair()``. Use ``"127.0.0.1"``
+  (IPv4) or ``"::1"`` (IPv6) host instead of ``"localhost"``, because
+  ``"localhost"`` may be a different IP address. Reject also invalid arguments:
+  only ``AF_INET`` and ``AF_INET6`` with ``SOCK_STREAM`` (and ``proto=0``) are
+  supported.
+* Tulip issue #158: ``Task._step()`` now also sets ``self`` to ``None`` if an
+  exception is raised. ``self`` is set to ``None`` to break a reference cycle.
+
+
+2014-03-04: version 0.2
+=======================
+
+Trollius now uses ``yield From(...)`` syntax which looks close to Tulip ``yield
+from ...`` and allows to port more easily Trollius code to Tulip. The usage of
+``From()`` is not mandatory yet, but it may become mandatory in a future
+version.  However, if ``yield`` is used without ``From``, an exception is
+raised if the event loop is running in debug mode.
+
+Major changes:
+
+* Replace ``yield ...`` syntax with ``yield From(...)``
+* On Python 2, Future.set_exception() now only saves the traceback if the debug
+  mode of the event loop is enabled for best performances in production mode.
+  Use ``loop.set_debug(True)`` to save the traceback.
+
+Bugfixes:
+
+* Fix ``BaseEventLoop.default_exception_handler()`` on Python 2: get the
+  traceback from ``sys.exc_info()``
+* Fix unit tests on SSL sockets on Python older than 2.6.6. Example:
+  Mac OS 10.6 with Python 2.6.1 or OpenIndiana 148 with Python 2.6.4.
+* Fix error handling in the asyncio.time_monotonic module
+* Fix acquire() method of Lock, Condition and Semaphore: don't return a context
+  manager but True, as Tulip. Task._step() now does the trick.
+
+Other changes:
+
+* tox.ini: set PYTHONASYNCIODEBUG to 1 to run tests
+
+2014-02-25: version 0.1.6
+=========================
+
+Trollius changes:
+
+* Add a new Sphinx documentation:
+  http://trollius.readthedocs.org/
+* tox: pass posargs to nosetests. Patch contributed by Ian Wienand.
+* Fix support of Python 3.2 and add py32 to tox.ini
+* Merge with Tulip 0.4.1
+
+Major changes of Tulip 0.4.1:
+
+* Issue #81: Add support for UNIX Domain Sockets. New APIs:
+
+  - loop.create_unix_connection()
+  - loop.create_unix_server()
+  - streams.open_unix_connection()
+  - streams.start_unix_server()
+
+* Issue #80: Add new event loop exception handling API. New APIs:
+
+  - loop.set_exception_handler()
+  - loop.call_exception_handler()
+  - loop.default_exception_handler()
+
+* Issue #136: Add get_debug() and set_debug() methods to BaseEventLoopTests.
+  Add also a ``PYTHONASYNCIODEBUG`` environment variable to debug coroutines
+  since Python startup, to be able to debug coroutines defined directly in the
+  asyncio module.
+
+Other changes of Tulip 0.4.1:
+
+* asyncio.subprocess: Fix a race condition in communicate()
+* Fix _ProactorWritePipeTransport._pipe_closed()
+* Issue #139: Improve error messages on "fatal errors".
+* Issue #140: WriteTransport.set_write_buffer_size() to call
+  _maybe_pause_protocol()
+* Issue #129: BaseEventLoop.sock_connect() now raises an error if the address
+  is not resolved (hostname instead of an IP address) for AF_INET and
+  AF_INET6 address families.
+* Issue #131: as_completed() and wait() now raises a TypeError if the list of
+  futures is not a list but a Future, Task or coroutine object
+* Python issue #20495: Skip test_read_pty_output() of test_asyncio on FreeBSD
+  older than FreeBSD 8
+* Issue #130: Add more checks on subprocess_exec/subprocess_shell parameters
+* Issue #126: call_soon(), call_soon_threadsafe(), call_later(), call_at()
+  and run_in_executor() now raise a TypeError if the callback is a coroutine
+  function.
+* Python issue #20505: BaseEventLoop uses again the resolution of the clock
+  to decide if scheduled tasks should be executed or not.
+
+
+2014-02-10: version 0.1.5
+=========================
+
+- Merge with Tulip 0.3.1:
+
+  * New asyncio.subprocess module
+  * _UnixWritePipeTransport now also supports character devices, as
+    _UnixReadPipeTransport. Patch written by Jonathan Slenders.
+  * StreamReader.readexactly() now raises an IncompleteReadError if the
+    end of stream is reached before we received enough bytes, instead of
+    returning less bytes than requested.
+  * poll and epoll selectors now round the timeout away from zero (instead of
+    rounding towards zero) to fix a performance issue
+  * asyncio.queue: Empty renamed to QueueEmpty, Full to QueueFull
+  * _fatal_error() of _UnixWritePipeTransport and _ProactorBasePipeTransport
+    don't log BrokenPipeError nor ConnectionResetError
+  * Future.set_exception(exc) now instanciate exc if it is a class
+  * streams.StreamReader: Use bytearray instead of deque of bytes for internal
+    buffer
+
+- Fix test_wait_for() unit test
+
+2014-01-22: version 0.1.4
+=========================
+
+- The project moved to https://bitbucket.org/enovance/trollius
+- Fix CoroWrapper (_DEBUG=True): add missing import
+- Emit a warning when Return is not raised
+- Merge with Tulip to get latest Tulip bugfixes
+- Fix dependencies in tox.ini for the different Python versions
+
+2014-01-13: version 0.1.3
+=========================
+
+- Workaround bugs in the ssl module of Python older than 2.6.6. For example,
+  Mac OS 10.6 (Snow Leopard) uses Python 2.6.1.
+- ``return x, y`` is now written ``raise Return(x, y)`` instead of
+  ``raise Return((x, y))``
+- Support "with (yield lock):" syntax for Lock, Condition and Semaphore
+- SSL support is now optional: don't fail if the ssl module is missing
+- Add tox.ini, tool to run unit tests. For example, "tox -e py27" creates a
+  virtual environment to run tests with Python 2.7.
+
+2014-01-08: version 0.1.2
+=========================
+
+- Trollius now supports CPython 2.6-3.4, PyPy and Windows. All unit tests
+  pass with CPython 2.7 on Linux.
+- Fix Windows support. Fix compilation of the _overlapped module and add a
+  asyncio._winapi module (written in pure Python). Patch written by Marc
+  Schlaich.
+- Support Python 2.6: require an extra dependency,
+  ordereddict (and unittest2 for unit tests)
+- Support Python 3.2, 3.3 and 3.4
+- Support PyPy 2.2
+- Don't modify __builtins__ nor the ssl module to inject backported exceptions
+  like BlockingIOError or SSLWantReadError. Exceptions are available in the
+  asyncio module, ex: asyncio.BlockingIOError.
+
+2014-01-06: version 0.1.1
+=========================
+
+- Fix asyncio.time_monotonic on Mac OS X
+- Fix create_connection(ssl=True)
+- Don't export backported SSLContext in the ssl module anymore to not confuse
+  libraries testing hasattr(ssl, "SSLContext")
+- Relax dependency on the backported concurrent.futures module: use a
+  synchronous executor if the module is missing
+
+2014-01-04: version 0.1
+=======================
+
+- First public release
+
diff --git a/doc/conf.py b/doc/conf.py
new file mode 100644
index 0000000..0bcd2da
--- /dev/null
+++ b/doc/conf.py
@@ -0,0 +1,240 @@
+# -*- coding: utf-8 -*-
+#
+# Trollius documentation build configuration file, created by
+# sphinx-quickstart on Fri Feb 21 11:05:42 2014.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#import sys, os
+#sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration -----------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = []
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'Trollius'
+copyright = u'2014, Victor Stinner'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = release = '1.0.5'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['build']
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+
+# -- Options for HTML output ---------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+html_theme = 'default'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'Trolliusdoc'
+
+
+# -- Options for LaTeX output --------------------------------------------------
+
+latex_elements = {
+# The paper size ('letterpaper' or 'a4paper').
+#'papersize': 'letterpaper',
+
+# The font size ('10pt', '11pt' or '12pt').
+#'pointsize': '10pt',
+
+# Additional stuff for the LaTeX preamble.
+#'preamble': '',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass [howto/manual]).
+latex_documents = [
+  ('index', 'Trollius.tex', u'Trollius Documentation',
+   u'Victor Stinner', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+
+# -- Options for manual page output --------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    ('index', 'trollius', u'Trollius Documentation',
+     [u'Victor Stinner'], 1)
+]
+
+# If true, show URL addresses after external links.
+#man_show_urls = False
+
+
+# -- Options for Texinfo output ------------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+  ('index', 'Trollius', u'Trollius Documentation',
+   u'Victor Stinner', 'Trollius', 'One line description of project.',
+   'Miscellaneous'),
+]
+
+# Documents to append as an appendix to all manuals.
+#texinfo_appendices = []
+
+# If false, no module index is generated.
+#texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#texinfo_show_urls = 'footnote'
diff --git a/doc/dev.rst b/doc/dev.rst
new file mode 100644
index 0000000..5965306
--- /dev/null
+++ b/doc/dev.rst
@@ -0,0 +1,85 @@
+Run tests
+=========
+
+Run tests with tox
+------------------
+
+The `tox project <https://testrun.org/tox/latest/>`_ can be used to build a
+virtual environment with all runtime and test dependencies and run tests
+against different Python versions (2.6, 2.7, 3.2, 3.3).
+
+For example, to run tests with Python 2.7, just type::
+
+    tox -e py27
+
+To run tests against other Python versions:
+
+* ``py26``: Python 2.6
+* ``py27``: Python 2.7
+* ``py32``: Python 3.2
+* ``py33``: Python 3.3
+
+
+Test Dependencies
+-----------------
+
+On Python older than 3.3, unit tests require the `mock
+<https://pypi.python.org/pypi/mock>`_ module. Python 2.6 requires also
+`unittest2 <https://pypi.python.org/pypi/unittest2>`_.
+
+To run ``run_aiotest.py``, you need the `aiotest
+<https://pypi.python.org/pypi/aiotest>`_ test suite: ``pip install aiotest``.
+
+
+Run tests on UNIX
+-----------------
+
+Run the following commands from the directory of the Trollius project.
+
+To run tests::
+
+    make test
+
+To run coverage (``coverage`` package is required)::
+
+    make coverage
+
+
+Run tests on Windows
+--------------------
+
+Run the following commands from the directory of the Trollius project.
+
+You can run the tests as follows::
+
+    C:\Python27\python.exe runtests.py
+
+And coverage as follows::
+
+    C:\Python27\python.exe runtests.py --coverage
+
+
+CPython bugs
+============
+
+The development of asyncio and trollius helped to identify different bugs in CPython:
+
+* 2.5.0 <= python <= 3.4.2: `sys.exc_info() bug when yield/yield-from is used
+  in an except block in a generator (#23353>)
+  <http://bugs.python.org/issue23353>`_.  The fix will be part of Python 3.4.3.
+  _UnixSelectorEventLoop._make_subprocess_transport() and
+  ProactorEventLoop._make_subprocess_transport() work around the bug.
+* python == 3.4.0: `Segfault in gc with cyclic trash (#21435)
+  <http://bugs.python.org/issue21435>`_.
+  Regression introduced in Python 3.4.0, fixed in Python 3.4.1.
+  Status in Ubuntu the February, 3th 2015: only Ubuntu Trusty (14.04 LTS) is
+  impacted (`bug #1367907:  Segfault in gc with cyclic trash
+  <https://bugs.launchpad.net/ubuntu/+source/python3.4/+bug/1367907>`_, see
+  also `update Python3 for trusty #1348954
+  <https://bugs.launchpad.net/ubuntu/+source/python3.4/+bug/1348954>`_)
+* 3.3.0 <= python <= 3.4.0: `gen.send(tuple) unpacks the tuple instead of
+  passing 1 argument (the tuple) when gen is an object with a send() method,
+  not a classic generator (#21209) <http://bugs.python.org/21209>`_.
+  Regression introduced in Python 3.4.0, fixed in Python 3.4.1.
+  trollius.CoroWrapper.send() works around the issue, the bug is checked at
+  runtime once, when the module is imported.
diff --git a/doc/index.rst b/doc/index.rst
new file mode 100644
index 0000000..8625093
--- /dev/null
+++ b/doc/index.rst
@@ -0,0 +1,80 @@
+Trollius
+========
+
+.. image:: trollius.jpg
+   :alt: Trollius altaicus from Khangai Mountains (Mongòlia)
+   :align: right
+   :target: http://commons.wikimedia.org/wiki/File:Trollius_altaicus.jpg
+
+Trollius provides infrastructure for writing single-threaded concurrent
+code using coroutines, multiplexing I/O access over sockets and other
+resources, running network clients and servers, and other related primitives.
+Here is a more detailed list of the package contents:
+
+* a pluggable event loop with various system-specific implementations;
+
+* transport and protocol abstractions (similar to those in `Twisted
+  <http://twistedmatrix.com/>`_);
+
+* concrete support for TCP, UDP, SSL, subprocess pipes, delayed calls, and
+  others (some may be system-dependent);
+
+* a ``Future`` class that mimics the one in the ``concurrent.futures`` module,
+  but adapted for use with the event loop;
+
+* coroutines and tasks based on generators (``yield``), to help write
+  concurrent code in a sequential fashion;
+
+* cancellation support for ``Future``\s and coroutines;
+
+* synchronization primitives for use between coroutines in a single thread,
+  mimicking those in the ``threading`` module;
+
+* an interface for passing work off to a threadpool, for times when you
+  absolutely, positively have to use a library that makes blocking I/O calls.
+
+Trollius is a portage of the `Tulip project <http://code.google.com/p/tulip/>`_
+(``asyncio`` module, `PEP 3156 <http://legacy.python.org/dev/peps/pep-3156/>`_)
+on Python 2. Trollius works on Python 2.6-3.5. It has been tested on Windows,
+Linux, Mac OS X, FreeBSD and OpenIndiana.
+
+* `Asyncio documentation <http://docs.python.org/dev/library/asyncio.html>`_
+* `Trollius documentation <http://trollius.readthedocs.org/>`_ (this document)
+* `Trollius project in the Python Cheeseshop (PyPI)
+  <https://pypi.python.org/pypi/trollius>`_ (download wheel packages and
+  tarballs)
+* `Trollius project at Bitbucket <https://bitbucket.org/enovance/trollius>`_
+  (bug tracker, source code)
+* Mailing list: `python-tulip Google Group
+  <https://groups.google.com/forum/?fromgroups#!forum/python-tulip>`_
+* IRC: ``#asyncio`` channel on the `Freenode network <https://freenode.net/>`_
+* Copyright/license: Open source, Apache 2.0. Enjoy!
+
+See also the `Tulip project <http://code.google.com/p/tulip/>`_ (asyncio module
+for Python 3.3).
+
+
+Table Of Contents
+=================
+
+.. toctree::
+
+   using
+   install
+   asyncio
+   dev
+   changelog
+
+
+Trollius name
+=============
+
+Extract of `Trollius Wikipedia article
+<http://en.wikipedia.org/wiki/Trollius>`_:
+
+Trollius is a genus of about 30 species of plants in the family Ranunculaceae,
+closely related to Ranunculus. The common name of some species is globeflower
+or globe flower. Native to the cool temperate regions of the Northern
+Hemisphere, with the greatest diversity of species in Asia, trollius usually
+grow in heavy, wet clay soils.
+
diff --git a/doc/install.rst b/doc/install.rst
new file mode 100644
index 0000000..ea2b455
--- /dev/null
+++ b/doc/install.rst
@@ -0,0 +1,111 @@
+++++++++++++++++
+Install Trollius
+++++++++++++++++
+
+Packages for Linux
+==================
+
+* `Debian package
+  <https://packages.debian.org/fr/sid/python-trollius>`_
+* `ArchLinux package
+  <https://aur.archlinux.org/packages/python2-trollius/>`_
+* `Fedora and CentOS package: python-trollius
+  <http://pkgs.org/download/python-trollius>`_
+
+
+Install Trollius on Windows using pip
+=====================================
+
+Since Trollius 0.2, `precompiled wheel packages <http://pythonwheels.com/>`_
+are now distributed on the Python Cheeseshop (PyPI). Procedure to install
+Trollius on Windows:
+
+* `Install pip
+  <http://www.pip-installer.org/en/latest/installing.html>`_, download
+  ``get-pip.py`` and type::
+
+  \Python27\python.exe get-pip.py
+
+* If you already have pip, ensure that you have at least pip 1.4. If you need
+  to upgrade::
+
+  \Python27\python.exe -m pip install -U pip
+
+* Install Trollius::
+
+  \Python27\python.exe -m pip install trollius
+
+* pip also installs the ``futures`` dependency
+
+.. note::
+
+   Only wheel packages for Python 2.7 are currently distributed on the
+   Cheeseshop (PyPI). If you need wheel packages for other Python versions,
+   please ask.
+
+Download source code
+====================
+
+Command to download the development version of the source code (``trollius``
+branch)::
+
+    hg clone 'https://bitbucket.org/enovance/trollius#trollius'
+
+The actual code lives in the ``trollius`` subdirectory. Tests are in the
+``tests`` subdirectory.
+
+See the `trollius project at Bitbucket
+<https://bitbucket.org/enovance/trollius>`_.
+
+The source code of the Trollius project is in the ``trollius`` branch of the
+Mercurial repository, not in the default branch. The default branch is the
+Tulip project, Trollius repository is a fork of the Tulip repository.
+
+
+Dependencies
+============
+
+On Python older than 3.2, the `futures <https://pypi.python.org/pypi/futures>`_
+project is needed to get a backport of ``concurrent.futures``.
+
+Python 2.6 requires also `ordereddict
+<https://pypi.python.org/pypi/ordereddict>`_.
+
+
+Build manually Trollius on Windows
+==================================
+
+On Windows, if you cannot use precompiled wheel packages, an extension module
+must be compiled: the ``_overlapped`` module (source code: ``overlapped.c``).
+Read `Compile Python extensions on Windows
+<http://haypo-notes.readthedocs.org/python.html#compile-python-extensions-on-windows>`_
+to prepare your environment to build the Python extension. Then build the
+extension using::
+
+    C:\Python27\python.exe setup.py build_ext
+
+
+Backports
+=========
+
+To support Python 2.6-3.4, many Python modules of the standard library have
+been backported:
+
+========================  =========  =======================
+Name                      Python     Backport
+========================  =========  =======================
+OSError                        3.3   asyncio.py33_exceptions
+_overlapped                    3.4   asyncio._overlapped
+_winapi                        3.3   asyncio.py33_winapi
+collections.OrderedDict   2.7, 3.1   ordereddict (PyPI)
+concurrent.futures             3.2   futures (PyPI)
+selectors                      3.4   asyncio.selectors
+ssl                       3.2, 3.3   asyncio.py3_ssl
+time.monotonic                 3.3   asyncio.time_monotonic
+unittest                  2.7, 3.1   unittest2 (PyPI)
+unittest.mock                  3.3   mock (PyPI)
+weakref.WeakSet           2.7, 3.0   asyncio.py27_weakrefset
+========================  =========  =======================
+
+
+
diff --git a/doc/make.bat b/doc/make.bat
new file mode 100644
index 0000000..5789d41
--- /dev/null
+++ b/doc/make.bat
@@ -0,0 +1,190 @@
+@ECHO OFF
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set BUILDDIR=_build
+set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
+set I18NSPHINXOPTS=%SPHINXOPTS% .
+if NOT "%PAPER%" == "" (
+	set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
+	set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%
+)
+
+if "%1" == "" goto help
+
+if "%1" == "help" (
+	: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.  text       to make text files
+	echo.  man        to make manual pages
+	echo.  texinfo    to make Texinfo files
+	echo.  gettext    to make PO message catalogs
+	echo.  changes    to make an overview over 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
+	goto end
+)
+
+if "%1" == "clean" (
+	for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
+	del /q /s %BUILDDIR%\*
+	goto end
+)
+
+if "%1" == "html" (
+	%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/html.
+	goto end
+)
+
+if "%1" == "dirhtml" (
+	%SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
+	goto end
+)
+
+if "%1" == "singlehtml" (
+	%SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
+	goto end
+)
+
+if "%1" == "pickle" (
+	%SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can process the pickle files.
+	goto end
+)
+
+if "%1" == "json" (
+	%SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can process the JSON files.
+	goto end
+)
+
+if "%1" == "htmlhelp" (
+	%SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can run HTML Help Workshop with the ^
+.hhp project file in %BUILDDIR%/htmlhelp.
+	goto end
+)
+
+if "%1" == "qthelp" (
+	%SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can run "qcollectiongenerator" with the ^
+.qhcp project file in %BUILDDIR%/qthelp, like this:
+	echo.^> qcollectiongenerator %BUILDDIR%\qthelp\Trollius.qhcp
+	echo.To view the help file:
+	echo.^> assistant -collectionFile %BUILDDIR%\qthelp\Trollius.ghc
+	goto end
+)
+
+if "%1" == "devhelp" (
+	%SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished.
+	goto end
+)
+
+if "%1" == "epub" (
+	%SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The epub file is in %BUILDDIR%/epub.
+	goto end
+)
+
+if "%1" == "latex" (
+	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
+	goto end
+)
+
+if "%1" == "text" (
+	%SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The text files are in %BUILDDIR%/text.
+	goto end
+)
+
+if "%1" == "man" (
+	%SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The manual pages are in %BUILDDIR%/man.
+	goto end
+)
+
+if "%1" == "texinfo" (
+	%SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo.
+	goto end
+)
+
+if "%1" == "gettext" (
+	%SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The message catalogs are in %BUILDDIR%/locale.
+	goto end
+)
+
+if "%1" == "changes" (
+	%SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.The overview file is in %BUILDDIR%/changes.
+	goto end
+)
+
+if "%1" == "linkcheck" (
+	%SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Link check complete; look for any errors in the above output ^
+or in %BUILDDIR%/linkcheck/output.txt.
+	goto end
+)
+
+if "%1" == "doctest" (
+	%SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Testing of doctests in the sources finished, look at the ^
+results in %BUILDDIR%/doctest/output.txt.
+	goto end
+)
+
+:end
diff --git a/doc/trollius.jpg b/doc/trollius.jpg
new file mode 100644
index 0000000..f4976c7
--- /dev/null
+++ b/doc/trollius.jpg
diff --git a/doc/using.rst b/doc/using.rst
new file mode 100644
index 0000000..c730f86
--- /dev/null
+++ b/doc/using.rst
@@ -0,0 +1,85 @@
+++++++++++++++
+Using Trollius
+++++++++++++++
+
+Documentation of the asyncio module
+===================================
+
+The documentation of the asyncio is part of the Python project. It can be read
+online: `asyncio - Asynchronous I/O, event loop, coroutines and tasks
+<http://docs.python.org/dev/library/asyncio.html>`_.
+
+To adapt asyncio examples for Trollius, "just":
+
+* replace ``asyncio`` with ``trollius``
+  (or use ``import trollius as asyncio``)
+* replace ``yield from ...`` with ``yield From(...)``
+* replace ``yield from []`` with ``yield From(None)``
+* in coroutines, replace ``return res`` with ``raise Return(res)``
+
+
+Trollius Hello World
+====================
+
+Print ``Hello World`` every two seconds, using a coroutine::
+
+    import trollius
+    from trollius import From
+
+    @trollius.coroutine
+    def greet_every_two_seconds():
+        while True:
+            print('Hello World')
+            yield From(trollius.sleep(2))
+
+    loop = trollius.get_event_loop()
+    loop.run_until_complete(greet_every_two_seconds())
+
+
+Debug mode
+==========
+
+To enable the debug mode:
+
+* Set ``TROLLIUSDEBUG`` envrironment variable to ``1``
+* Configure logging to log at level ``logging.DEBUG``,
+  ``logging.basicConfig(level=logging.DEBUG)`` for example
+
+The ``BaseEventLoop.set_debug()`` method can be used to set the debug mode on a
+specific event loop. The environment variable enables also the debug mode for
+coroutines.
+
+Effect of the debug mode:
+
+* On Python 2, :meth:`Future.set_exception` stores the traceback, so
+  ``loop.run_until_complete()`` raises the exception with the original
+  traceback.
+* Log coroutines defined but never "yielded"
+* BaseEventLoop.call_soon() and BaseEventLoop.call_at() methods raise an
+  exception if they are called from the wrong thread.
+* Log the execution time of the selector
+* Log callbacks taking more than 100 ms to be executed. The
+  BaseEventLoop.slow_callback_duration attribute is the minimum duration in
+  seconds of "slow" callbacks.
+* Log most important subprocess events:
+
+  - Log stdin, stdout and stderr transports and protocols
+  - Log process identifier (pid)
+  - Log connection of pipes
+  - Log process exit
+  - Log Process.communicate() tasks: feed stdin, read stdout and stderr
+
+* Log most important socket events:
+
+  - Socket connected
+  - New client (socket.accept())
+  - Connection reset or closed by peer (EOF)
+  - Log time elapsed in DNS resolution (getaddrinfo)
+  - Log pause/resume reading
+  - Log time of SSL handshake
+  - Log SSL handshake errors
+
+See `Debug mode of asyncio
+<https://docs.python.org/dev/library/asyncio-dev.html#debug-mode-of-asyncio>`_
+for more information.
+