diff --git a/README.rst b/README.rst index d86b81d..3509f0a 100644 --- a/README.rst +++ b/README.rst @@ -19,7 +19,8 @@ Ideas * Advanced section: - protocols and transports: as least point to good implementations - - explain how to *test* asyncio applications. `Twisted documentation example `_ + - explain how to *test* asyncio applications. `Twisted documentation example + `_ How to install Sphinx ===================== diff --git a/conf.py b/conf.py index e9dbaea..afc3dd9 100644 --- a/conf.py +++ b/conf.py @@ -16,9 +16,9 @@ # 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 os -# import sys -# sys.path.insert(0, os.path.abspath('.')) +import os +import sys +sys.path.insert(0, os.path.abspath('.')) # -- General configuration ------------------------------------------------ @@ -29,7 +29,7 @@ # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = [] +#extensions = ['alabaster'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -119,8 +119,25 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # +import alabaster html_theme = 'alabaster' +html_theme_path = [alabaster.get_path()] +extensions = ['alabaster', 'sphinx.ext.intersphinx'] +html_theme = 'alabaster' +html_sidebars = { + '**': [ + 'about.html', + 'navigation.html', + 'relations.html', + 'searchbox.html', + 'donate.html', + 'localtoc.html', + 'sourcelink.html', + ] +} +intersphinx_mapping = {'python': ('https://docs.python.org/3.5', None)} + # 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. diff --git a/getting_started.rst b/getting_started.rst index 6f773d0..dfd986a 100644 --- a/getting_started.rst +++ b/getting_started.rst @@ -5,17 +5,21 @@ Getting Started Get Python 3.5 ============== -Sorry but this documentation is written for Python 3.5 to avail of the new ``async`` +Sorry but this documentation is written for Python 3.5 to avail of the new +``async`` and ``await`` keywords. .. would be good to have some word about installing on Windows -* Windows: the easiest way to use Python 3.5 would be to use a package manager like Conda - There are instructions for using a python 3.5 environment in `Conda here `_. +* Windows: the easiest way to use Python 3.5 would be to use a package manager + like Conda + There are instructions for using a python 3.5 environment in `Conda here + `_. * Mac OS X: install `Homebrew `_ and then type ``brew install python3`` * Linux: Ubuntu 16.04+ and Arch linux ship with Python 3.5 included. - If you don't have Python 3.5+ on your computer, you can compile it or use `Pythonz `_ + If you don't have Python 3.5+ on your computer, you can compile it or use + `Pythonz `_ Create a virtual environment to run examples @@ -26,7 +30,8 @@ Create a virtual environment:: python3 -m venv venv .. note:: - Depending on your platform, the python 3 interpreter could be invoked by ``python`` instead. This is the case for Conda on Windows for example. + Depending on your platform, the python 3 interpreter could be invoked by + ``python`` instead. This is the case for Conda on Windows for example. Install aiohttp in the virtual environment:: diff --git a/glossary.rst b/glossary.rst index c59d624..82279c1 100644 --- a/glossary.rst +++ b/glossary.rst @@ -9,13 +9,22 @@ Glossary .. glossary:: coroutine - A coroutine is a piece of code that can be paused and resumed. In contrast to threads which are preemptively multitasked by the operating system, coroutines multitask cooperatively. I.e. they choose when to pause (or to use terminology for coroutines before 3.4 - ``yield``) execution. They can also execute other coroutines. + A coroutine is a piece of code that can be paused and resumed. In + contrast to threads which are preemptively multitasked by the operating + system, coroutines multitask cooperatively. I.e. they choose when to + pause (or to use terminology for coroutines before 3.4 - ``yield``) + execution. They can also execute other coroutines. event loop - The event loop is the central execution device to launch execution of coroutines and handle I/O (Network, sub-processes...) + The event loop is the central execution device to launch execution of + coroutines and handle I/O (Network, sub-processes...) future - It's like a mailbox where you can subscribe to receive a result when it will be done. More details in `official documentation `_ + It's like a mailbox where you can subscribe to receive a result when it + will be done. More details in `official documentation + `_ task - It represents the execution of a coroutine and take care the result in a future. More details in `official documentation `_ + It represents the execution of a coroutine and take care the result in a + future. More details in `official documentation + `_ diff --git a/hello_clock.rst b/hello_clock.rst index 52227cc..67c9c6f 100644 --- a/hello_clock.rst +++ b/hello_clock.rst @@ -1,10 +1,12 @@ Hello Clock ^^^^^^^^^^^ -Example illustrating how to schedule two :term:`coroutines ` to run concurrently. -They run for ten minutes, during which the first :term:`coroutine ` is scheduled every -second, while the second is scheduled every minute. +Example illustrating how to schedule two :term:`coroutines ` to run +concurrently. They run for ten minutes, during which the first :term:`coroutine +` is scheduled to run every second, while the second is scheduled to +run every minute. -The function `asyncio.gather` is used to schedule both :term:`coroutines ` at once. +The function `asyncio.gather` is used to schedule both :term:`coroutines +` at once. .. literalinclude:: examples/hello_clock.py diff --git a/hello_world.rst b/hello_world.rst index 7209204..7493039 100644 --- a/hello_world.rst +++ b/hello_world.rst @@ -2,16 +2,19 @@ Hello World +++++++++++ -This is a series of examples showing the basics of how write :term:`coroutines ` and +This is a series of examples showing the basics of how write :term:`coroutines +` and schedule them in the asyncio :term:`event loop `. Simple coroutine ---------------- -Example using the :meth:`BaseEventLoop.run_until_complete` method to schedule a +Example using the :py:meth:`asyncio.BaseEventLoop.run_until_complete` method to +schedule a simple function that will wait one second, print 'hello' and then finish. -Because it is launched with `run_until_complete`, the :term:`event loop ` itself +Because it is launched with `run_until_complete`, the :term:`event loop ` itself will terminate once the :term:`coroutine ` is completed. .. literalinclude:: examples/hello_world.py @@ -20,13 +23,16 @@ will terminate once the :term:`coroutine ` is completed. Creating tasks -------------- -This second example show how you can schedule multiple :term:`coroutines ` in the +This second example show how you can schedule multiple :term:`coroutines +` in the event loop, and then run the :term:`event loop `. Notice that this example will print 'second_hello' before 'first_hello', -as the first :term:`task ` scheduled waits longer that the second one before printing. +as the first :term:`task ` scheduled waits longer that the second one +before printing. -Also note that this example will never terminate, as the :term:`loop ` is asked to +Also note that this example will never terminate, as the :term:`loop ` is asked to `run_forever`. .. literalinclude:: examples/create_task.py @@ -35,7 +41,8 @@ Also note that this example will never terminate, as the :term:`loop ` that will stop the :term:`event loop ` before +This third example adds another :term:`task ` that will stop the +:term:`event loop ` before all scheduled :term:`tasks ` could execute, which results in a warning. .. literalinclude:: examples/loop_stop.py @@ -43,5 +50,6 @@ all scheduled :term:`tasks ` could execute, which results in a warning. Warning:: Task was destroyed but it is pending! - task: wait_for=> + task: + wait_for=> diff --git a/index.rst b/index.rst index 9865b18..3db5b3d 100644 --- a/index.rst +++ b/index.rst @@ -51,3 +51,11 @@ See also * `Writing Redis in Python with asyncio: Part 1 `_ by James Saryerwinnie + +Contributing +============ + +.. toctree:: + :maxdepth: 2 + + README.rst