Add first draft of Sphinx documentation

19 files changed, 408 insertions, 0 deletions

diff --git a/docs/Makefile b/docs/Makefile
new file mode 100644
index 0000000..d0c3cbf
--- /dev/null
+++ b/docs/Makefile
@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/make.bat b/docs/make.bat
new file mode 100644
index 0000000..6247f7e
--- /dev/null
+++ b/docs/make.bat
@@ -0,0 +1,35 @@
+@ECHO OFF

+

+pushd %~dp0

+

+REM Command file for Sphinx documentation

+

+if "%SPHINXBUILD%" == "" (

+	set SPHINXBUILD=sphinx-build

+)

+set SOURCEDIR=source

+set BUILDDIR=build

+

+if "%1" == "" goto help

+

+%SPHINXBUILD% >NUL 2>NUL

+if errorlevel 9009 (

+	echo.

+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx

+	echo.installed, then set the SPHINXBUILD environment variable to point

+	echo.to the full path of the 'sphinx-build' executable. Alternatively you

+	echo.may add the Sphinx directory to PATH.

+	echo.

+	echo.If you don't have Sphinx installed, grab it from

+	echo.http://sphinx-doc.org/

+	exit /b 1

+)

+

+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%

+goto end

+

+:help

+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%

+

+:end

+popd

diff --git a/docs/source/abnf.rst b/docs/source/abnf.rst
new file mode 100644
index 0000000..04d3adc
--- /dev/null
+++ b/docs/source/abnf.rst
@@ -0,0 +1,8 @@
+##################
+websocket/_abnf.py
+##################
+
+The _abnf.py file
+
+.. automodule:: websocket._abnf
+  :members:
diff --git a/docs/source/about.rst b/docs/source/about.rst
new file mode 100644
index 0000000..58dca79
--- /dev/null
+++ b/docs/source/about.rst
@@ -0,0 +1,10 @@
+#####
+About
+#####
+
+The websocket-client project was started in 2011, but experienced a slowdown in
+development in 2019-2020. The original creator of this project was
+`liris <https://github.com/liris>`_ and the current maintainer (as of 2021) is
+`engn33r <https://github.com/engn33r>`_. The project is in the process of being
+rejuvenated, so any edits or suggestions are appreciated. No typo is too small
+for a pull request! See the :ref:`contributing` page for more info.
diff --git a/docs/source/app.rst b/docs/source/app.rst
new file mode 100644
index 0000000..4f5d4b2
--- /dev/null
+++ b/docs/source/app.rst
@@ -0,0 +1,8 @@
+#################
+websocket/_app.py
+#################
+
+The _app.py file
+
+.. automodule:: websocket._app
+  :members:
diff --git a/docs/source/conf.py b/docs/source/conf.py
new file mode 100644
index 0000000..8b19aeb
--- /dev/null
+++ b/docs/source/conf.py
@@ -0,0 +1,63 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# 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('../..'))
+
+# Don't skip __init__, which is skipped by default
+def skip(app, what, name, obj, would_skip, options):
+    if name == "__init__":
+        return False
+    return would_skip
+
+def setup(app):
+    app.connect("autodoc-skip-member", skip)
+
+# -- Project information -----------------------------------------------------
+
+project = 'websocket-client'
+copyright = '2021'
+author = 'liris'
+
+# The full version, including alpha/beta/rc tags
+release = '0.57.0'
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.coverage',
+'sphinx.ext.napoleon', 'sphinx.ext.viewcode', 'sphinx.ext.autosectionlabel']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+
+# 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']
diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst
new file mode 100644
index 0000000..e033981
--- /dev/null
+++ b/docs/source/contributing.rst
@@ -0,0 +1,22 @@
+############
+Contributing
+############
+
+All contributions are welcome! To submit a suggestion, you can either create a
+new issue (after searching for an existing issue that covers the same topic)
+or submit a pull request with the edits that you would like to see in the
+repository.
+
+If you are contributing to the project's documentation, which is still in its
+early stages, it is recommended that you install Sphinx and build the updated
+documentation locally before submitting
+your edits. The Sphinx dependencies can be installed by navigating to the
+docs/source directory and running ``pip install -r requirements.txt``. To build
+a new version of the documentation, navigate to the docs/ directory and run
+``make clean html``. Any build warnings or errors will be displayed in your
+terminal, and the new documentation will then be available in the
+docs/build/html directory. You may also find the
+`Sphinx documentation style guide
+<https://documentation-style-guide-sphinx.readthedocs.io/en/latest/style-guide.html>`_
+useful when editing reStructuredText (reST), which is quite different from
+Markdown.
diff --git a/docs/source/core.rst b/docs/source/core.rst
new file mode 100644
index 0000000..e7235a7
--- /dev/null
+++ b/docs/source/core.rst
@@ -0,0 +1,8 @@
+##################
+websocket/_core.py
+##################
+
+The _core.py file
+
+.. automodule:: websocket._core
+  :members:
diff --git a/docs/source/examples.rst b/docs/source/examples.rst
new file mode 100644
index 0000000..189b6ed
--- /dev/null
+++ b/docs/source/examples.rst
@@ -0,0 +1,9 @@
+########
+Examples
+########
+
+This page needs help! Please see the :ref:`contributing` page to make it better!
+
+For now, you can try out the :ref:`getting started` wsdump.py script and the
+`examples/ <https://github.com/websocket-client/websocket-client/tree/master/examples>`_
+directory files.
diff --git a/docs/source/exceptions.rst b/docs/source/exceptions.rst
new file mode 100644
index 0000000..9761bdf
--- /dev/null
+++ b/docs/source/exceptions.rst
@@ -0,0 +1,8 @@
+########################
+websocket/_exceptions.py
+########################
+
+The _exceptions.py file
+
+.. automodule:: websocket._exceptions
+  :members:
diff --git a/docs/source/faq.rst b/docs/source/faq.rst
new file mode 100644
index 0000000..47619f4
--- /dev/null
+++ b/docs/source/faq.rst
@@ -0,0 +1,74 @@
+###
+FAQ
+###
+
+How to disable ssl cert verification?
+=======================================
+
+Set the sslopt to ``{"cert_reqs": ssl.CERT_NONE}``. The same sslopt argument is
+provided for all examples seen below.
+
+**WebSocketApp example**
+
+::
+
+  ws = websocket.WebSocketApp("wss://echo.websocket.org")
+  ws.run_forever(sslopt={"cert_reqs": ssl.CERT_NONE})
+
+
+**create_connection example**
+
+::
+
+  ws = websocket.create_connection("wss://echo.websocket.org",
+    sslopt={"cert_reqs": ssl.CERT_NONE})
+
+**WebSocket example**
+
+::
+
+  ws = websocket.WebSocket(sslopt={"cert_reqs": ssl.CERT_NONE})
+  ws.connect("wss://echo.websocket.org")
+
+
+How to disable hostname verification?
+=======================================
+
+Please set sslopt to ``{"check_hostname": False}``. (since v0.18.0)
+
+**WebSocketApp example**
+
+::
+
+  ws = websocket.WebSocketApp("wss://echo.websocket.org")
+  ws.run_forever(sslopt={"check_hostname": False})
+
+**create_connection example**
+
+::
+
+  ws = websocket.create_connection("wss://echo.websocket.org",
+    sslopt={"check_hostname": False})
+
+**WebSocket example**
+
+::
+
+  ws = websocket.WebSocket(sslopt={"check_hostname": False})
+  ws.connect("wss://echo.websocket.org")
+
+How to enable `SNI <http://en.wikipedia.org/wiki/Server_Name_Indication>`_?
+============================================================================
+
+SNI support is available for Python 2.7.9+ and 3.2+.
+It will be enabled automatically whenever possible.
+
+Using Subprotocols
+====================
+
+The WebSocket RFC
+`outlines the usage of subprotocols <https://tools.ietf.org/html/rfc6455#section-1.9>`_
+The subprotocol can be specified as in the example below:
+
+>>> ws = websocket.create_connection("ws://example.com/websocket",
+  subprotocols=["binary", "base64"])
diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst
new file mode 100644
index 0000000..b040e60
--- /dev/null
+++ b/docs/source/getting_started.rst
@@ -0,0 +1,53 @@
+###############
+Getting Started
+###############
+
+The quickest way to get started with this library is to use the wsdump.py
+script, found in the
+`bin/ <https://github.com/websocket-client/websocket-client/tree/master/bin>`_
+directory. For an easy example, run the following:
+
+::
+
+  python wsdump.py ws://echo.websocket.org/ -t "hello world"
+
+The above command will provide you with an interactive terminal to communicate
+with the echo.websocket.org server. This server will echo back any message you
+send it. You can test this WebSocket connection in your browser, without this
+library, by visiting the URL https://websocket.org/echo.html.
+
+The wsdump.py script has many additional options too, so it's a great way to try
+using this library without writing any custom code. The output of
+``python wsdump.py -h`` is seen below, showing the additional options available.
+
+::
+
+  python wsdump.py -h
+  usage: wsdump.py [-h] [-p PROXY] [-v [VERBOSE]] [-n] [-r]
+                   [-s [SUBPROTOCOLS [SUBPROTOCOLS ...]]] [-o ORIGIN]
+                   [--eof-wait EOF_WAIT] [-t TEXT] [--timings]
+                   [--headers HEADERS]
+                   ws_url
+
+  WebSocket Simple Dump Tool
+
+  positional arguments:
+    ws_url                websocket url. ex. ws://echo.websocket.org/
+
+  optional arguments:
+    -h, --help            show this help message and exit
+    -p PROXY, --proxy PROXY
+                          proxy url. ex. http://127.0.0.1:8080
+    -v [VERBOSE], --verbose [VERBOSE]
+                          set verbose mode. If set to 1, show opcode. If set to
+                          2, enable to trace websocket module
+    -n, --nocert          Ignore invalid SSL cert
+    -r, --raw             raw output
+    -s [SUBPROTOCOLS [SUBPROTOCOLS ...]], --subprotocols [SUBPROTOCOLS [SUBPROTOCOLS ...]]
+                          Set subprotocols
+    -o ORIGIN, --origin ORIGIN
+                          Set origin
+    --eof-wait EOF_WAIT   wait time(second) after 'EOF' received.
+    -t TEXT, --text TEXT  Send initial text
+    --timings             Print timings in seconds
+    --headers HEADERS     Set custom headers. Use ',' as separator
diff --git a/docs/source/index.rst b/docs/source/index.rst
new file mode 100644
index 0000000..a48e181
--- /dev/null
+++ b/docs/source/index.rst
@@ -0,0 +1,36 @@
+###########################################
+Welcome to websocket-client's documentation
+###########################################
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Introduction:
+
+   installation
+   getting_started
+   examples
+   threading
+   faq
+   contributing
+   about
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Comments Embedded in Code:
+
+   abnf
+   app
+   core
+   exceptions
+   logging
+   socket
+   url
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+
+..
+  * :ref:`search`
diff --git a/docs/source/installation.rst b/docs/source/installation.rst
new file mode 100644
index 0000000..c990799
--- /dev/null
+++ b/docs/source/installation.rst
@@ -0,0 +1,16 @@
+############
+Installation
+############
+
+First, install the following dependencies:
+  - six
+  - backports.ssl_match_hostname (only for Python 2.x)
+
+To install the Python 2 dependencies, use:
+``pip install six backports.ssl_match_hostname``
+
+To install the Python 3 dependencies, use:
+``pip install six``
+
+You can use either ``python setup.py install`` or
+``pip install websocket-client`` to install this library.
diff --git a/docs/source/logging.rst b/docs/source/logging.rst
new file mode 100644
index 0000000..ea73bc0
--- /dev/null
+++ b/docs/source/logging.rst
@@ -0,0 +1,8 @@
+#####################
+websocket/_logging.py
+#####################
+
+The _logging.py file
+
+.. automodule:: websocket._logging
+  :members:
diff --git a/docs/source/requirements.txt b/docs/source/requirements.txt
new file mode 100644
index 0000000..1ff9106
--- /dev/null
+++ b/docs/source/requirements.txt
@@ -0,0 +1,2 @@
+Sphinx>=3.4
+sphinx_rtd_theme>=0.5
diff --git a/docs/source/socket.rst b/docs/source/socket.rst
new file mode 100644
index 0000000..6c46f7f
--- /dev/null
+++ b/docs/source/socket.rst
@@ -0,0 +1,8 @@
+####################
+websocket/_socket.py
+####################
+
+The _socket.py file
+
+.. automodule:: websocket._socket
+  :members:
diff --git a/docs/source/threading.rst b/docs/source/threading.rst
new file mode 100644
index 0000000..15f5531
--- /dev/null
+++ b/docs/source/threading.rst
@@ -0,0 +1,12 @@
+#########
+Threading
+#########
+
+This page needs help! Please see the :ref:`contributing` page to make it better!
+
+There are over a dozen open issues on this topic, including:
+
+  - `#496 <https://github.com/websocket-client/websocket-client/issues/496>`_
+  - `#562 <https://github.com/websocket-client/websocket-client/issues/562>`_
+  - `#580 <https://github.com/websocket-client/websocket-client/issues/580>`_
+  - `#591 <https://github.com/websocket-client/websocket-client/issues/591>`_
diff --git a/docs/source/url.rst b/docs/source/url.rst
new file mode 100644
index 0000000..0f0edbd
--- /dev/null
+++ b/docs/source/url.rst
@@ -0,0 +1,8 @@
+#################
+websocket/_url.py
+#################
+
+The _url.py file
+
+.. automodule:: websocket._url
+  :members: