have pytest run code examples in docs + have travis build docs

.travis.yml

@@ -4,7 +4,8 @@ python: 3.5
 sudo: false
 
 install:
-  - python3 setup.py install
+  - travis_retry pip install -e .[test]
 
 script:
   - python3 -m pytest
+  - sphinx-build -nq -b html -b linkcheck -d docs/_build/doctrees docs docs/_build/html

curio/task.py

@@ -2,7 +2,7 @@
 #
 # Task class and task related functions.
 
-__all__ = [ 'sleep', 'current_task', 'spawn', 'gather', 'timeout_after', 'ignore_after', 'wait' ]
+__all__ = [ 'Task', 'sleep', 'current_task', 'spawn', 'gather', 'timeout_after', 'ignore_after', 'wait' ]
 
 from .errors import TaskTimeout, TaskError
 from .traps import *

docs/devel.rst

@@ -82,16 +82,16 @@ Defining a Coroutine
 
 A coroutine is a function defined using ``async def`` such as this::
 
-    async def greeting(name):
-        return 'Hello ' + name
+    >>> async def greeting(name):
+    ...     return 'Hello ' + name
 
 Unlike a normal function, a coroutine never executes independently.
 It has to be driven by some other code.  It's low-level, but you can
 drive a coroutine manually if you want::
 
     >>> g = greeting('Dave')
     >>> g
-    <coroutine object greeting at 0x10ded14c0>
+    <coroutine object greeting at ...>
     >>> g.send(None)
     Traceback (most recent call last):
       File "<stdin>", line 1, in <module>
@@ -115,13 +115,16 @@ Coroutines Calling Coroutines
 Coroutines can call other coroutines as long as you preface the call
 with the ``await`` keyword.  For example::
 
-    async def main():
-         names = ['Dave', 'Paula', 'Thomas', 'Lewis']
-         for name in names:
-             print(await greeting(name))
-
-    from curio import run
-    run(main())
+    >>> async def main():
+    ...      names = ['Dave', 'Paula', 'Thomas', 'Lewis']
+    ...      for name in names:
+    ...          print(await greeting(name))
+    >>> from curio import run
+    >>> run(main())
+    Hello Dave
+    Hello Paula
+    Hello Thomas
+    Hello Lewis
 
 For the most part, you can write async functions, methods, and do everything that you
 would do with normal Python functions.  The use of the ``await`` in calls is important
@@ -149,31 +152,29 @@ completes the request and reschedules the process.
 Now, what does all of this have to do with coroutines?  Let's define
 a very special kind of coroutine::
 
-   from types import coroutine
-
-   @coroutine
-   def sleep(seconds):
-       yield ('sleep', seconds)
+   >>> from types import coroutine
+   >>> @coroutine
+   ... def sleep(seconds):
+   ...     yield ('sleep', seconds)
 
 This coroutine is different than the rest--it doesn't use the
 ``async`` syntax and it makes direct use of the ``yield`` statement
 (which is not normally allowed in ``async`` functions).  The ``@coroutine``
 decorator is there so that it can be called with ``await``.
 Now, let's write a coroutine that uses this::
 
-   async def main():
-       print('Yawn. Getting sleepy.')
-       await sleep(10)
-       print('Awake at last!')
+   >>> async def main():
+   ...     print('Yawn. Getting sleepy.')
+   ...     await sleep(10)
+   ...     print('Awake at last!')
 
 Let's manually drive it using the same technique as before::
 
     >>> c = main()
     >>> request = c.send(None)
-    Yawn! Getting sleepy.
+    Yawn. Getting sleepy.
     >>> request
     ('sleep', 10)
-    >>> 
 
 The output from the first ``print()`` function appears, but the
 coroutine is now suspended. The return value of the
@@ -192,7 +193,6 @@ return result if any).   For example::
     Traceback (most recent call last):
       File "<stdin>", line 1, in <module>
     StopIteration
-    >>> 
 
 All of this might seem very low-level, but this is precisely what
 Curio is doing. Coroutines execute statements under the

docs/index.rst

@@ -22,9 +22,10 @@ Contents:
 .. toctree::
    :maxdepth: 2
 
-* :doc:`tutorial` 
-* :doc:`reference`
-* :doc:`howto`
+   tutorial
+   reference
+   howto
+   devel
 
 Installation:
 -------------
@@ -91,7 +92,7 @@ of the code::
         run(tcp_server('', 25000, echo_client))
 
 This is only a small sample of what's possible.  The `tutorial 
-<https://curio.readthedocs.org/en/latest/tutorial.html>`_ is a good starting point
+<https://curio.readthedocs.io/en/latest/tutorial.html>`_ is a good starting point
 for more information.
 
 Additional Features

docs/reference.rst

@@ -44,7 +44,7 @@ run a top-level coroutine using the following function:
    crash.  If *with_monitor* is ``True``, then the monitor debugging
    task executes in the background.  If *selector* is given, it should
    be an instance of a selector from the :mod:`selectors
-   <python:selector>` module.
+   <python:selectors>` module.
 
 If you are going to repeatedly run coroutines one after the other, it
 will be more efficient to create a ``Kernel`` instance and submit
@@ -76,8 +76,8 @@ The following functions are defined to help manage the execution of tasks.
 
    Create a new task that runs the coroutine *coro*.  Does not
    return to the caller until the new task has been scheduled and
-   executed for at least one cycle.  Returns a :class:`Task` instance
-   as a result.  The *daemon* option, if supplied, specifies that the
+   executed for at least one cycle.  Returns a :class:`Task <curio.task.Task>`
+   instance as a result.  The *daemon* option, if supplied, specifies that the
    new task will run indefinitely in the background.  Curio only runs
    as long as there are non-daemonic tasks to execute.  Note: a
    daemonic task will still be cancelled if the underlying kernel is

docs/tutorial.rst

@@ -983,7 +983,7 @@ More Information
 The official Github page at https://github.com/dabeaz/curio should be used for bug reports,
 pull requests, and other activities. 
 
-A reference manual can be found at https://curio.readthedocs.org/en/latest/reference.html.
+A reference manual can be found at https://curio.readthedocs.io/en/latest/reference.html.
 
 
 

pytest.ini

@@ -0,0 +1,9 @@
+[pytest]
+; uncomment when ready to test code samples in docs:
+;testpaths = tests docs
+testpaths = tests
+addopts = --verbose
+          --ignore=setup.py --ignore=docs/conf.py
+;         --doctest-modules --doctest-glob=docs/*.rst
+; uncomment ^^^ when ready to test code samples in docs
+doctest_optionflags = IGNORE_EXCEPTION_DETAIL ELLIPSIS

setup.py

@@ -3,6 +3,8 @@
 except ImportError:
     from distutils.core import setup
 
+tests_require = ['pytest', 'Sphinx']
+
 setup(name = "curio",
             description="Curio - Concurrent I/O",
             long_description = """
@@ -16,6 +18,10 @@
             maintainer_email = "dave@dabeaz.com",
             url = "https://github.com/dabeaz/curio",
             packages = ['curio'],
+            tests_require = tests_require,
+            extras_require = {
+                'test': tests_require,
+              },
             classifiers = [
               'Programming Language :: Python :: 3',
               ]