Some docs fixes (#1031)

* Explicitly set bash sphinx lexer

* Avoid sphinx warning about missing term

* Add notes on websocket read methods usage

* Fix stray md inline literal

docs/index.rst

@@ -24,12 +24,14 @@ Features
 Library Installation
 --------------------
 
-::
+.. code-block:: bash
 
    $ pip install aiohttp
 
 You may want to install *optional* :term:`cchardet` library as faster
-replacement for :term:`chardet`::
+replacement for :term:`chardet`:
+
+.. code-block:: bash
 
    $ pip install cchardet
 
@@ -114,7 +116,9 @@ Dependencies
 - *Optional* :term:`cchardet` library as faster replacement for
   :term:`chardet`.
 
-  Install it explicitly via::
+  Install it explicitly via:
+
+  .. code-block:: bash
 
      $ pip install cchardet
 

docs/web_reference.rst

@@ -844,13 +844,18 @@ WebSocketResponse
 
       :raise ValueError: if data is not serializable object
 
-      :raise TypeError: if value returned by :term:`dumps` is not :class:`str`
+      :raise TypeError: if value returned by ``dumps`` param is not :class:`str`
 
    .. coroutinemethod:: close(*, code=1000, message=b'')
 
       A :ref:`coroutine<coroutine>` that initiates closing
       handshake by sending :const:`~aiohttp.WSMsgType.close` message.
 
+      .. note::
+
+         Can only be called by the request handling task. To programmatically
+         close websocket server side see the :ref:`FAQ section <aiohttp_faq_terminating_websockets>`.
+
       :param int code: closing code
 
       :param message: optional payload of *pong* message,
@@ -876,6 +881,10 @@ WebSocketResponse
       :exc:`~aiohttp.errors.WSClientDisconnectedError` with
       connection closing data.
 
+      .. note::
+
+         Can only be called by the request handling task.
+
       :return: :class:`~aiohttp.WSMessage`
 
       :raise RuntimeError: if connection is not started
@@ -888,6 +897,10 @@ WebSocketResponse
       also asserts the message type is
       :const:`~aiohttp.WSMsgType.text`.
 
+      .. note::
+
+         Can only be called by the request handling task.
+
       :return str: peer's message content.
 
       :raise TypeError: if message is :const:`~aiohttp.WSMsgType.binary`.
@@ -898,6 +911,10 @@ WebSocketResponse
       also asserts the message type is
       :const:`~aiohttp.WSMsgType.binary`.
 
+      .. note::
+
+         Can only be called by the request handling task.
+
       :return bytes: peer's message content.
 
       :raise TypeError: if message is :const:`~aiohttp.WSMsgType.text`.
@@ -907,6 +924,10 @@ WebSocketResponse
       A :ref:`coroutine<coroutine>` that calls :meth:`receive_str` and loads the
       JSON string to a Python dict.
 
+      .. note::
+
+         Can only be called by the request handling task.
+
       :param callable loads: any :term:`callable` that accepts
                               :class:`str` and returns :class:`dict`
                               with parsed JSON (:func:`json.loads` by
@@ -932,7 +953,7 @@ json_response
                             dumps=json.dumps)
 
 Return :class:`Response` with predefined ``'application/json'``
-content type and *data* encoded by *dumps* parameter
+content type and *data* encoded by ``dumps`` parameter
 (:func:`json.dumps` by default).