Reshuffle and enhance documentation

2 files changed, 76 insertions, 4 deletions

diff --git a/docs/source/examples.rst b/docs/source/examples.rst
index 038181a..a11bb23 100644
--- a/docs/source/examples.rst
+++ b/docs/source/examples.rst
@@ -241,6 +241,26 @@ Disabling SSL or Hostname Verification
 
 See the relevant :ref:`FAQ` page for instructions.
 
+Using a Custom Class
+--------------------------------
+
+You can also write your own class for the connection, if you want to handle
+the nitty-gritty connection details yourself.
+
+::
+
+  import socket
+  from websocket import create_connection, WebSocket
+  class MyWebSocket(WebSocket):
+    def recv_frame(self):
+        frame = super().recv_frame()
+        print('yay! I got this frame: ', frame)
+        return frame
+
+  ws = create_connection("ws://echo.websocket.org/",
+                        sockopt=((socket.IPPROTO_TCP, socket.TCP_NODELAY, 1),), class_=MyWebSocket)
+
+
 Setting Timeout Value
 --------------------------------
 
@@ -299,7 +319,11 @@ Connecting through a HTTP proxy
 
 The example below show how to connect through a HTTP proxy. Note that this
 library does support authentication to a proxy using the ``http_proxy_auth``
-parameter.
+parameter. Be aware that the current implementation of websocket-client uses
+the "CONNECT" method, and the proxy server must allow the "CONNECT" method. For
+example, the squid proxy only allows the "CONNECT" method
+`on HTTPS ports <https://wiki.squid-cache.org/Features/HTTPS#CONNECT_tunnel>`_
+by default.
 
 **WebSocket proxy example**
 
@@ -353,7 +377,7 @@ message opcodes as part of the protocol. These can serve as a way to keep a
 long-lived connection active even if data is not being transmitted. However, if
 a blocking event is happening, there may be some issues with ping/pong. The
 below examples demonstrate how ping and pong can be sent by this library. You
-can getaddition debugging information by using
+can get additional debugging information by using
 `Wireshark <https://www.wireshark.org/>`_
 to view the ping and pong messages being sent. In order for Wireshark to
 identify the WebSocket protocol properly, it should observe the initial HTTP
@@ -380,9 +404,9 @@ This type of connection does not automatically respond to a "ping" with a "pong"
 
 **WebSocketApp ping/pong example**
 
-This example, and run_forever in general, is better for long-lived connections.
+This example, and ``run_forever()`` in general, is better for long-lived connections.
 If a server needs a regular ping to keep the connection alive, this is probably
-the option you will want to use. The run_forever connection will automatically
+the option you will want to use. The ``run_forever()`` function will automatically
 send a "pong" when it receives a "ping", per the specification.
 
 ::
@@ -401,3 +425,18 @@ send a "pong" when it receives a "ping", per the specification.
   wsapp = websocket.WebSocketApp("wss://stream.meetup.com/2/rsvps",
     on_message=on_message, on_ping=on_ping, on_pong=on_pong)
   wsapp.run_forever(ping_interval=10, ping_timeout=60)
+
+Real-world Examples
+=========================
+
+Other projects that depend on websocket-client may be able to illustrate more
+complex use cases for this library. A few of the projects using websocket-client
+are listed below:
+
+- `https://github.com/slackapi/python-slack-sdk <https://github.com/slackapi/python-slack-sdk>`_
+- `https://github.com/wee-slack/wee-slack <https://github.com/wee-slack/wee-slack>`_
+- `https://github.com/aluzzardi/wssh/ <https://github.com/aluzzardi/wssh/>`_
+- `https://github.com/invisibleroads/socketIO-client <https://github.com/invisibleroads/socketIO-client>`_
+- `https://github.com/Ape/samsungctl <https://github.com/Ape/samsungctl>`_
+- `https://github.com/xchwarze/samsung-tv-ws-api <https://github.com/xchwarze/samsung-tv-ws-api>`_
+- `https://github.com/andresriancho/websocket-fuzzer <https://github.com/andresriancho/websocket-fuzzer>`_
diff --git a/docs/source/faq.rst b/docs/source/faq.rst
index 797d94f..eadacad 100644
--- a/docs/source/faq.rst
+++ b/docs/source/faq.rst
@@ -2,6 +2,39 @@
 FAQ
 ###
 
+Why is this library slow?
+===========================
+
+The ``send`` and ``validate_utf8`` methods are very slow in pure Python.
+If you want to get better performance, please install both numpy and wsaccel.
+Note that wsaccel can sometimes cause other issues.
+
+How to solve the "connection is already closed" error?
+===========================================================
+
+The WebSocketConnectionClosedException, which returns the message "Connection
+is already closed.", occurs when a WebSocket function such as ``send()`` or
+``recv()`` is called but the WebSocket connection is already closed. One way
+to handle exceptions in Python is by using
+`a try/except <https://docs.python.org/3/tutorial/errors.html#handling-exceptions>`_
+statement, which allows you to control what your program does if the WebSocket
+connection is closed when you try to use it. In order to properly carry out
+further functions with your WebSocket connection after the connection has
+closed, you will need to reconnect the WebSocket, using ``connect()`` or
+``create_connection()`` (from the _core.py file). The WebSocketApp ``run_forever()``
+function automatically tries to reconnect when the connection is lost.
+
+What's going on with the naming of this library?
+==================================================
+
+To install this library, you use ``pip3 install websocket-client``, while ``import
+websocket`` imports this library, and PyPi lists the package as
+``websocket_client``. Why is it so confusing? To see the original issue about
+the choice of ``import websocket``, see
+`issue #60 <https://github.com/websocket-client/websocket-client/issues/60>`_
+and to read about websocket-client vs. websocket_client, see
+`issue #147 <https://github.com/websocket-client/websocket-client/issues/147>`_
+
 How to disable ssl cert verification?
 =======================================