Avoid warnings when building the docs

Author: Vincent Michel

conf.py

@@ -173,7 +173,7 @@
 # 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 = ['_static']
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied

getting_started.rst

@@ -8,9 +8,11 @@ Python 3.5 (or higher) only
 This documentation is written for Python 3.5 to avail of the new
 ``async`` and ``await`` keywords.
 
-If you have Python 3.5 installed you only need to install ``aiohttp``::
+If you have Python 3.5 installed you only need to install ``aiohttp``:
 
-    pip install -U aiohttp
+.. sourcecode:: console
+
+    $ pip install -U aiohttp
 
 If you don't have Python 3.5 installed yet, you have several options
 to install it.
@@ -21,27 +23,37 @@ All platforms with ``conda``
 * Download and install
   `Miniconda <http://conda.pydata.org/miniconda.html>`_  for our platform.
 * Create a new Python 3.5 environment (named ``aio35``, use a different
-  if you like)::
+  if you like):
+
+  .. sourcecode:: console
 
-       conda create -n aio35 python=3.5
+       $ conda create -n aio35 python=3.5
 
 * Activate it.
-  Linux and OS X::
+  Linux and OS X:
+
+  .. sourcecode:: console
 
        $ source activate aio35
 
-  Windows::
+  Windows:
+
+  .. sourcecode:: console
 
        $ source activate aio35
 
-* Install ``aiohttp``::
+* Install ``aiohttp``:
+
+  .. sourcecode:: console
 
        $(aio35) pip install aiohttp
 
+
 Platform specific
 -----------------
 
 .. 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
   such as conda. See the installation instructions above.
 * Mac OS X: Install `Homebrew </usr/bin/ruby -e "$(curl -fsSL
@@ -55,15 +67,18 @@ Platform specific
 Create a virtual environment to run examples
 ============================================
 
-If you don't use conda (see above), create a virtual environment::
+If you don't use conda (see above), create a virtual environment:
+
+.. sourcecode:: console
 
-    python3 -m venv venv
+    $ 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.
 
-Install ``aiohttp`` in the virtual environment::
+Install ``aiohttp`` in the virtual environment:
 
-    ./venv/bin/python -m pip install -U aiohttp
+.. sourcecode:: console
 
+    $ ./venv/bin/python -m pip install -U aiohttp

glossary.rst

@@ -21,10 +21,11 @@ Glossary
 
     future
         It's like a mailbox where you can subscribe to receive a result when it
-        will be done. More details in `official documentation
-        <https://docs.python.org/3/library/asyncio-task.html#future>`_
+        will be done. See the `Future section`_ of the official documentation.
 
     task
         It represents the execution of a coroutine and take care the result in a
-        future. More details in `official documentation
-        <https://docs.python.org/3/library/asyncio-task.html#task>`_
+        future. See the `Task section`_ of the official documentation.
+
+.. _Future section: https://docs.python.org/3/library/asyncio-task.html#future
+.. _Task section: https://docs.python.org/3/library/asyncio-task.html#task

hello_world.rst

@@ -47,9 +47,12 @@ all scheduled :term:`tasks <task>` could execute, which results in a warning.
 
 .. literalinclude:: examples/loop_stop.py
 
-Warning::
+Output:
 
+.. sourcecode:: console
+
+    second hello
+    first hello
     Task was destroyed but it is pending!
     task: <Task pending coro=<say() done, defined at examples/loop_stop.py:3>
     wait_for=<Future pending cb=[Task._wakeup()]>>
-

webscraper.rst

@@ -19,28 +19,40 @@ A Mock Web Server
 
 This is a very simple web server. (See below for the code.)
 Its only purpose is to wait for a given amount of time.
-Test it by running it from the command line::
+Test it by running it from the command line:
+
+.. sourcecode:: console
 
     $ python simple_server.py
 
-It will answer like this::
+It will answer like this:
+
+.. sourcecode:: console
 
     Serving from port 8000 ...
 
-Now, open a browser and go to this URL::
+Now, open a browser and go to this URL:
+
+.. sourcecode:: console
 
     http://localhost:8000/
 
-You should see this text in your browser::
+You should see this text in your browser:
+
+.. sourcecode:: console
 
     Waited for 0.00 seconds.
 
-Now, add ``2.5`` to the URL::
+Now, add ``2.5`` to the URL:
+
+.. sourcecode:: console
 
    http://localhost:8000/2.5
 
 After pressing enter, it will take 2.5 seconds until you see this
-response::
+response:
+
+.. sourcecode:: console
 
     Waited for 2.50 seconds.
 
@@ -49,7 +61,6 @@ Use different numbers and see how long it takes until the server responds.
 The full implementation looks like this:
 
 .. literalinclude:: examples/simple_server.py
-    :language: python
 
 Let's have a look into the details.
 This provides a simple multi-threaded web server:
@@ -113,11 +124,15 @@ The function ``time.perf_counter()`` provides a time stamp.
 Taking two time stamps a different points in time and calculating their
 difference provides the elapsed run time.
 
-Finally, we can run our client::
+Finally, we can run our client:
+
+.. sourcecode:: console
 
     $ python synchronous_client.py
 
-and get this output::
+and get this output:
+
+.. sourcecode:: console
 
     It took 11.08 seconds for a total waiting time of 11.00.
     Waited for 1.00 seconds.
@@ -174,9 +189,7 @@ Therefore, we need to convert our strings in to bytestrings.
 Next, we read header and message from the reader, which is a ``StreamReader``
 instance.
 We need to iterate over the reader by using a special or loop for
-``asyncio``:
-
-.. code-block:: python
+``asyncio``::
 
     async for raw_line in reader:
 
@@ -204,14 +217,15 @@ The interesting things happen in a few lines in ``get_multiple_pages()``
 (the rest of this function just measures the run time and displays it):
 
 .. literalinclude:: examples/async_client_blocking.py
-    :language: python
     :start-after: pages = []
     :end-before: duration
 
 We await ``get_page()`` for each page in a loop.
 This means, we wait until each pages has been retrieved before asking for
 the next.
-Let's run it from the command-line to see what happens::
+Let's run it from the command-line to see what happens:
+
+.. sourcecode:: console
 
     $ async_client_blocking.py
     It took 11.06 seconds for a total waiting time of 11.00.
@@ -249,28 +263,26 @@ The interesting part is in this loop:
 We append all return values of ``get_page()`` to our lits of tasks.
 This allows us to send out all request, in our case four, without
 waiting for the answers.
-After sending all of them, we wait for the answers, using:
+After sending all of them, we wait for the answers, using::
 
     await asyncio.gather(*tasks)
 
 The difference here is the use of ``asyncio.gather()`` that is called with all
 our tasks in the list ``tasks`` as arguments.
-The ``asyncio.gather(*tasks)`` means for our example with four list entries:
-
-.. code-block:: python
+The ``asyncio.gather(*tasks)`` means for our example with four list entries::
 
     asyncio.gather(tasks[0], tasks[1], tasks[2], tasks[3])
 
-So, for a list with 100 tasks it would mean:
-
-.. code-block:: python
+So, for a list with 100 tasks it would mean::
 
     asyncio.gather(tasks[0], tasks[1], tasks[2],
                    # 96 more tasks here
                    tasks[99])
 
 
-Let's see if we got any faster::
+Let's see if we got any faster:
+
+.. sourcecode:: console
 
     $ async_client_nonblocking.py
     It took 5.08 seconds for a total waiting time of 11.00.
@@ -309,10 +321,11 @@ High-Level Approach with ``aiohttp``
 
 The library aiohttp_ allows to write HTTP client and server applications,
 using a high-level approach.
-Install with::
+Install with:
 
-    $ pip install aiohttp
+.. sourcecode:: console
 
+    $ pip install aiohttp
 
 .. _aiohttp: https://aiohttp.readthedocs.io/en/stable/
 
@@ -352,7 +365,9 @@ with ``asyncio``.
 The only difference is the opened client session and handing over this session
 to ``fetch_page()`` as the first argument.
 
-Finally, we run this program::
+Finally, we run this program:
+
+.. sourcecode:: console
 
     $ python aiohttp_client.py
     It took 5.04 seconds for a total waiting time of 11.00.