add spelling checks

.gitignore

@@ -49,7 +49,8 @@ coverage.xml
 *.log
 
 # Sphinx documentation
-docs/_build/
+doc/_build/
+doc/_spelling/
 
 # PyBuilder
 target/

Makefile

@@ -19,6 +19,9 @@ install:
 docs:
 	cd doc && make html
 
+spelling:
+	cd doc && sphinx-build -b spelling . _spelling
+
 pep8:
 	pep8 test/*.py txaio/*.py
 
@@ -37,6 +40,8 @@ clean:
 	rm -rf ./.eggs
 	rm -rf ./.cache
 	rm -rf ./test/.coverage.*.*
+	rm -rf ./doc/_build
+	rm -rf ./doc/_spelling
 	find . -name "*.tar.gz" -type f -exec rm -f {} \;
 	find . -name "*.egg" -type f -exec rm -f {} \;
 	find . -name "*.pyc" -type f -exec rm -f {} \;

doc/api.rst

@@ -1,5 +1,5 @@
-txaio API
-=========
+API
+===
 
 The API is identical whether you're using Twisted or asyncio under the
 hood. Two ``bool`` variables are available if you need to know which
@@ -26,7 +26,7 @@ Set an Event Loop / Reactor
 ---------------------------
 
 You can set ``txaio.config.loop`` to either an EventLoop instance (if
-using asyncio) or an explicit reactor (if using Twisted). By defualt,
+using asyncio) or an explicit reactor (if using Twisted). By default,
 ``reactor`` is imported from ``twisted.internet`` on the first
 ``call_later`` invocation. For asyncio, ``asyncio.get_event_loop()``
 is called at import time.
@@ -107,7 +107,7 @@ txaio module
         txaio.add_callbacks(p, do_something, it_failed)
 
     You therefore don't have to worry if the underlying function was
-    itself asynchronous or not -- your code always treats it as async.
+    itself asynchronous or not -- your code always treats it as asynchronous.
 
 
 .. py:function:: reject(future, error=None)

doc/conf.py

@@ -16,6 +16,7 @@
 import sys
 import os
 import shlex
+import time
 
 # 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
@@ -33,8 +34,14 @@ sys.path.insert(0, os.path.abspath('..'))
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.viewcode',
+    'sphinx.ext.intersphinx',
+    'sphinxcontrib.spelling',
 ]
 
+spelling_lang = 'en_US'
+spelling_show_suggestions = False
+spelling_word_list_filename = 'spelling_wordlist.txt'
+
 # custom txaio extension configuration
 
 autodoc_member_order = 'bysource'
@@ -54,28 +61,33 @@ source_suffix = '.rst'
 #source_encoding = 'utf-8-sig'
 
 # The master toctree document.
-master_doc = 'index'
+master_doc = 'contents'
 
 # General information about the project.
-project = 'txaio'
-copyright = '2015, Tavendo GmbH'
-author = 'Tavendo'
+project = u'txaio'
+author = u'Tavendo'
+this_year = u'{0}'.format(time.strftime('%Y'))
+if this_year != u'2015':
+    copyright = u'2015-{0}, Tavendo GmbH'.format(this_year)
+else:
+    copyright = u'2015, Tavendo GmbH'
 
 # 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 = '0.0.0'
-# The full version, including alpha/beta/rc tags.
-release = '0.0.0'
+base_dir = os.path.abspath(os.path.join(os.path.dirname(__file__), os.pardir))
+with open(os.path.join(base_dir, "txaio", "_version.py")) as f:
+   exec(f.read())  # defines __version__
+
+version = release = __version__
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
@@ -148,7 +160,7 @@ html_theme = 'alabaster'
 # 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']
+html_static_path = []
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
@@ -164,7 +176,18 @@ html_static_path = ['_static']
 #html_use_smartypants = True
 
 # Custom sidebar templates, maps document names to template names.
-#html_sidebars = {}
+# Show full, global TOC in sidebar
+# http://stackoverflow.com/a/19007358
+# http://sphinx-doc.org/config.html#confval-html_sidebars
+html_sidebars = {
+    '**': [
+        'globaltoc.html',
+        'relations.html',
+        'sourcelink.html',
+        'searchbox.html'
+    ],
+}
+
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.
@@ -293,3 +316,10 @@ texinfo_documents = [
 
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 #texinfo_no_detailmenu = False
+
+# http://sphinx-doc.org/ext/intersphinx.html
+intersphinx_mapping = {
+   'py2': ('http://docs.python.org/2', None),
+   'py3': ('http://docs.python.org/3', None),
+   'six': ('https://pythonhosted.org/six/', None),
+}

doc/contents.rst

@@ -0,0 +1,14 @@
+:tocdepth: 0
+:orphan:
+
+.. _site_contents:
+
+Contents
+========
+
+.. toctree::
+   :maxdepth: 3
+
+   index
+   overview
+   api

doc/index.rst

@@ -1,5 +1,5 @@
-txaio: Twisted/asyncio helper
-=============================
+txaio
+=====
 
 | |Version| |Downloads| |Build Status| |Coverage| |Docs|
 
@@ -19,8 +19,8 @@ loop of either Twisted or asyncio**. This is different from attaching
 either one's event loop to the other using some event loop adapter.
 
 
-Supported Platforms
--------------------
+Platform support
+----------------
 
 **txaio** runs on CPython 2.6+ and PyPy 2, on top of Twisted or asyncio. Specifically, **txaio** is tested on the following platforms:
 
@@ -31,8 +31,8 @@ Supported Platforms
 * PyPy 2.5 on Twisted 12.1, 13.2, 15.4, trunk and Trollius 2.0
 
 
-How txaio Works
----------------
+How it works
+------------
 
 Instead of directly importing, instantiating and using ``Deferred``
 (for Twisted) or ``Future`` (for asyncio) objects, **txaio** provides
@@ -57,6 +57,9 @@ Code like the following can then run on *either* system:
     txaio.reject(f1, RuntimeError("it failed"))
 
 
+.. toctree::
+
+
 .. |Version| image:: https://img.shields.io/pypi/v/txaio.svg
    :target: https://pypi.python.org/pypi/txaio
 

doc/overview.rst

@@ -1,6 +1,5 @@
-txaio Overview
-==============
-
+Overview
+========
 
 Brief History
 -------------
@@ -18,7 +17,7 @@ own to other projects using event-based Python.
 Overview by Example
 -------------------
 
-The simplest way to use ``txaio`` is to ``import txaio`` and use the
+The simplest way to use **txaio** is to ``import txaio`` and use the
 helper functions directly. Using the library in this manner will
 automatically select the event-loop to use: Twisted if it's available,
 then asyncio and finally Trollius if those fail.
@@ -28,7 +27,7 @@ If you wish to be explicit about the event-loop you want, call
 (with an ``ImportError``) if that implementation isn't available.
 
 Note that to use this library successfully you *shouldn't* call
-methods on futures -- use *only* ``txaio`` methods to operate on them.
+methods on futures -- use *only* **txaio** methods to operate on them.
 
 .. sourcecode:: python
 
@@ -66,8 +65,8 @@ methods on futures -- use *only* ``txaio`` methods to operate on them.
 Restrictions and Caveats
 ------------------------
 
-``txaio`` is not a new event-based programming solution. It is not a
-complete box-set of async tools.
+**txaio** is not a new event-based programming solution. It is not a
+complete box-set of asynchronous programming tools.
 
 It is **one piece** that *can* help you to write cross-event-loop
 asynchronous code. For example, you'll note that there's no way to run
@@ -101,12 +100,12 @@ callback. Similarly, errbacks in Twisted can cancel the error. There
 are not equivalent facilities in ``asyncio``: if you add multiple
 callbacks, they all get the same value (or exception).
 
-When using ``txaio``, **don't depend on chaining**. This means that
+When using **txaio**, **don't depend on chaining**. This means that
 your ``callback`` and ``errback`` methods must **always return their
 input argument** so that Twisted works if you add multiple callbacks
 or errbacks (and doesn't unexpectedly cancel errors).
 
-``txaio`` does add the concept of an ``errback`` for handling errors
+**txaio** does add the concept of an ``errback`` for handling errors
 (a concept asyncio does not have) and therefore adds one helper to
 encapsulate exceptions (similar to Twisted's `Failure`_ object) which
 only exists in the asyncio implementation.
@@ -139,17 +138,17 @@ You are encouraged to look at `Autobahn|Python`_ for an example of a
 system that can run on both Twisted and asyncio. In particular, look
 at the difference between ``autobahn/twisted/websocket.py`` and
 ``autobahn/asyncio/websocket.py`` and the compatibility super-class in
-``autobahn/wamp/protocol.py`` which is the piece that uses ``txaio``
+``autobahn/wamp/protocol.py`` which is the piece that uses **txaio**
 to provide an event-loop agnostic implementation that both the Twisted
 and asyncio concrete ``ApplicationSession`` objects inherit from.
 
 ``autobahn.wamp.protocol.ApplicationSession`` is glued to a particular
 event-loop via ``autobahn.twisted.wamp.ApplicationSession`` which
-takes advantage of ``txaio.tx.LoopMixin`` to provde the
+takes advantage of ``txaio.tx.LoopMixin`` to provide the
 helpers-methods attached to ``self``.
 
 In this manner, code in the generic implementation simply always calls
-``txaio`` methods via ``self.create_future()`` or similar and users of
+**txaio** methods via ``self.create_future()`` or similar and users of
 `Autobahn|Python`_ can choose between asyncio and Twisted as they prefer
 by either ``from autobahn.twisted.wamp import ApplicationSession`` or
 ``from autobahn.asyncio.wamp import ApplicationSession``

doc/spelling_wordlist.txt

@@ -0,0 +1,18 @@
+txaio
+asyncio
+trollius
+deferred
+deferreds
+errback
+errbacks
+callback
+callbacks
+api
+cpython
+CPython
+arg
+args
+kwarg
+kwargs
+callables
+stdlib

setup.py

@@ -72,12 +72,14 @@ setup(
     ],
     extras_require={
         'dev': [
-            'pytest>=2.6.4',     # MIT
-            'pytest-cov>=1.8.1', # MIT
-            'pep8>=1.6.2',       # MIT
-            'Sphinx>=1.2.3',     # BSD
-            'alabaster>=0.6.3',  # BSD
-            'tox>=2.1.1'         # MIT
+            'pytest>=2.6.4',        # MIT
+            'pytest-cov>=1.8.1',    # MIT
+            'pep8>=1.6.2',          # MIT
+            'sphinx>=1.2.3',        # BSD
+            'pyenchant>=1.6.6',     # LGPL
+            'sphinxcontrib-spelling>=2.1.2',    # BSD
+            'alabaster>=0.6.3',     # BSD
+            'tox>=2.1.1'            # MIT
         ],
         'twisted': [
             'zope.interface>=3.6',  # Zope Public License

txaio/interfaces.py

@@ -122,7 +122,7 @@ class IFailedFuture(object):
     Deferred.
 
     An instance implementing this interface is given to any
-    ``errback`` callables you provde via :meth:`txaio.add_callbacks`
+    ``errback`` callables you provide via :meth:`txaio.add_callbacks`
 
     In your errback you can extract information from an IFailedFuture
     with :meth:`txaio.failure_message` and