Skip to content

Commit 319e960

Browse files
LawouachLawouach
committed
reworked docs
1 parent 628eed1 commit 319e960

12 files changed

Lines changed: 144 additions & 77 deletions

‎docs/conf.py‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,8 @@
3333
'sphinx.ext.autosummary',
3434
'sphinx.ext.coverage',
3535
'sphinx.ext.viewcode',
36-
'sphinx.ext.intersphinx']
36+
'sphinx.ext.intersphinx',
37+
'sphinxcontrib.seqdiag']
3738
autoclass_content = 'init'
3839
autodoc_member_order = 'bysource'
3940
intersphinx_mapping = {'python': ('http://docs.python.org/2.7', None)}
@@ -103,7 +104,7 @@
103104

104105
# The theme to use for HTML and HTML Help pages. See the documentation for
105106
# a list of builtin themes.
106-
html_theme = 'nature'
107+
html_theme = 'sphinxdoc'
107108

108109
# Theme options are theme-specific and customize the look and feel of a theme
109110
# further. For a list of options available for each theme, see the
@@ -260,7 +261,7 @@
260261
epub_title = u'ws4py'
261262
epub_author = u'Sylvain Hellegouarch'
262263
epub_publisher = u'Sylvain Hellegouarch'
263-
epub_copyright = u'2011 - 2012, Sylvain Hellegouarch'
264+
epub_copyright = u'2011 - 2013, Sylvain Hellegouarch'
264265

265266
# The language of the text. It defaults to the language option
266267
# or en if the language is not set.

‎docs/index.rst‎

Lines changed: 26 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,46 +1,55 @@
11
ws4py - A WebSocket package for Python
22
======================================
33

4+
Release v\ |version|.
5+
46
ws4py is a Python package implementing the WebSocket protocol as defined in `RFC 6455 <http://tools.ietf.org/html/rfc6455>`_.
57

68
It provides client and server implementations alike that using different techniques like threads, micro-threads or event loops.
79

8-
Requirements
9-
------------
10+
Getting Started
11+
===============
1012

1113
.. toctree::
12-
:maxdepth: 2
14+
:maxdepth: 1
1315

14-
requirements
16+
sources/requirements
17+
sources/install
1518

16-
Install
17-
-------
19+
20+
Tutorial
21+
========
1822

1923
.. toctree::
2024
:maxdepth: 2
2125

22-
install
26+
sources/basics
27+
sources/clienttutorial
28+
sources/servertutorial
29+
sources/managertutorial
2330

31+
Maintainer Guide
32+
================
2433

25-
Tutorial
26-
--------
34+
This section describes the steps to work on ws4py itself and its release
35+
process, as well as other conventions and best practices.
2736

2837
.. toctree::
29-
:maxdepth: 2
38+
:maxdepth: 1
3039

31-
basics
32-
clienttutorial
33-
servertutorial
34-
managertutorial
40+
sources/maintainer/rules
41+
sources/maintainer/design
42+
sources/maintainer/testing
43+
sources/maintainer/documenting
44+
sources/maintainer/releasing
3545

3646
Packages
37-
--------
47+
========
3848

3949
.. toctree::
4050
:maxdepth: 6
4151

42-
ws4py
43-
52+
sources/ws4py
4453

4554
Indices and tables
4655
==================

‎docs/requirements.rst‎

Lines changed: 0 additions & 37 deletions
This file was deleted.

docs/basics.rst renamed to docs/sources/basics.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,13 @@
11
Basics
2-
============
2+
======
33

4-
ws4py provides high-level, yet simple, interface to provide your application with WebSocket support.
4+
ws4py provides a high-level, yet simple, interface to provide your application with WebSocket support. It simples as:
55

66
.. code-block:: python
77
88
from ws4py.websocket import WebSocket
99
10-
The :class:`WebSocket <ws4py.websocket.WebSocket>` class should be sub-classed by your application to make something sensible with it. To the very least we suggest you override the :func:`received_message(message) <ws4py.websocket.WebSocket.received_message>` method.
10+
The :class:`WebSocket <ws4py.websocket.WebSocket>` class should be sub-classed by your application. To the very least we suggest you override the :func:`received_message(message) <ws4py.websocket.WebSocket.received_message>` method so that you can process incoming messages.
1111

1212
For instance a straightforward echo application would look like this:
1313

docs/clienttutorial.rst renamed to docs/sources/clienttutorial.rst

Lines changed: 57 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,15 @@
11
Client
22
======
33

4+
ws4py comes with various client implementations and they roughly share the same interface.
5+
6+
47
Built-in
58
--------
69

7-
ws4py comes with various client implementation but they roughly share the same aspects when your application needs one.
8-
9-
An example is better than any word so let's have a look at a basic client:
10+
The built-in client relies only on modules provided by the Python stdlib. The
11+
client's inner loop runs within a thread and teherfore holds the thread alive
12+
until the websocket is closed.
1013

1114
.. code-block:: python
1215
:linenos:
@@ -29,22 +32,21 @@ An example is better than any word so let's have a look at a basic client:
2932
print "Closed down", code, reason
3033
3134
def received_message(self, m):
32-
print "=> %d %s" % (len(m), str(m))
33-
if len(str(m)) == 175:
35+
print m
36+
if len(m) == 175:
3437
self.close(reason='Bye bye')
3538
3639
if __name__ == '__main__':
3740
try:
3841
ws = DummyClient('ws://localhost:9000/', protocols=['http-only', 'chat'])
3942
ws.connect()
43+
ws.join()
4044
except KeyboardInterrupt:
4145
ws.close()
4246
43-
This example demonstrates how to implement a client, here based on a thread-model, that is able to send and receive messages from a connected endpoint at ws://localhost:9000/.
44-
4547
In this snippet, when the handshake is successful, the :meth:`opened() <ws4py.websocket.WebSocket.opened>` method is called and within this method we immediatly send to the server a bunch of messages. First we demonstrate how you can use a generator to do so, then we simply send strings.
4648

47-
Assuming the server echoes messages as they arrive, the :func:`received_message(message) <ws4py.websocket.WebSocket.received_message>` method will print out the messages returned by the server and simply closes the connection once it receives the last sent messages , which length is 175.
49+
Assuming the server echoes messages as they arrive, the :func:`received_message(message) <ws4py.websocket.WebSocket.received_message>` method will print out the messages returned by the server and simply close the connection once it receives the last sent messages, which length is 175.
4850

4951
Finally the :func:`closed(code, reason=None) <ws4py.websocket.WebSocket.closed>` method is called with the code and reason given by the server.
5052

@@ -60,19 +62,63 @@ If you are using a Tornado backend you may use the Tornado client that ws4py pro
6062
.. code-block:: python
6163
6264
from ws4py.client.tornadoclient import WebSocketClient
65+
from tornado import ioloop
66+
67+
class MyClient(TornadoWebSocketClient):
68+
def opened(self):
69+
for i in range(0, 200, 25):
70+
self.send("*" * i)
71+
72+
def received_message(self, m):
73+
print m
74+
if len(m) == 175:
75+
self.close(reason='Bye bye')
6376
64-
The previous example runs exactly in the same way.
77+
def closed(self, code, reason=None):
78+
ioloop.IOLoop.instance().stop()
6579
80+
ws = MyClient('ws://localhost:9000/echo', protocols=['http-only', 'chat'])
81+
ws.connect()
82+
83+
ioloop.IOLoop.instance().start()
6684
6785
gevent
6886
------
6987

7088
If you are using a gevent backend you may use the gevent client that ws4py provides as follow:
7189

72-
7390
.. code-block:: python
7491
7592
from ws4py.client.geventclient import WebSocketClient
7693
77-
The previous example runs exactly in the same way.
94+
This client can benefit from gevent's concepts as demonstrated below:
95+
96+
97+
.. code-block:: python
98+
99+
ws = WebSocketClient('ws://localhost:9000/echo', protocols=['http-only', 'chat'])
100+
ws.connect()
101+
102+
def incoming():
103+
"""
104+
Greenlet waiting for incoming messages
105+
until ``None`` is received, indicating we can
106+
leave the loop.
107+
"""
108+
while True:
109+
m = ws.receive()
110+
if m is not None:
111+
print str(m)
112+
else:
113+
break
114+
115+
def send_a_bunch():
116+
for i in range(0, 40, 5):
117+
ws.send("*" * i)
118+
119+
greenlets = [
120+
gevent.spawn(incoming),
121+
gevent.spawn(send_a_bunch),
122+
]
123+
gevent.joinall(greenlets)
78124

docs/install.rst renamed to docs/sources/install.rst

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
1+
Install ws4py
2+
=============
3+
14
Get the code
2-
============
5+
------------
36

47
ws4py is hosted on `github <https://github.com/Lawouach/WebSocket-for-Python>`_ and can be retrieved from there:
58

@@ -8,9 +11,6 @@ ws4py is hosted on `github <https://github.com/Lawouach/WebSocket-for-Python>`_
811
$ git clone git@github.com:Lawouach/WebSocket-for-Python.git
912
1013
11-
Install the code
12-
================
13-
1414
Installing the ws4py package is performed as usual:
1515

1616
.. code-block:: guess
@@ -24,4 +24,7 @@ However, since ws4py is referenced in `PyPI <http://pypi.python.org/pypi/ws4py>`
2424
$ pip install ws4py
2525
$ easy_install ws4py
2626
27+
.. note::
2728

29+
ws4py explicitely will not automatically pull out its dependencies. Please install them
30+
manually depending on which imlementation you'll be using.

docs/managertutorial.rst renamed to docs/sources/managertutorial.rst

File renamed without changes.

‎docs/sources/requirements.rst‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
.. _requirements:
2+
3+
Requirements
4+
============
5+
6+
Python
7+
------
8+
9+
Tested environments:
10+
11+
- Python 2.7+
12+
- Python 3.2+
13+
- PyPy 1.8+
14+
15+
.. note::
16+
17+
ws4py will not try to automatically install dependencies and will
18+
let you decide which one you need.
19+
20+
Client
21+
------
22+
23+
ws4py comes with three client implementations:
24+
25+
- Built-in: That client is solely based on the Python stdlib, it uses a thread to run the inner processing loop.
26+
- Tornado: The Tornado client requires `Tornado <http://www.tornadoweb.org>`_ 2.0+
27+
- gevent: The gevent client requires `gevent <http://www.gevent.org/>`_ 0.13.6 or 1.0.0-dev
28+
29+
Server
30+
------
31+
32+
ws4py comes with three server implementations:
33+
34+
- Built-in: The server relies on the built-in :mod:`wsgiref` module.
35+
- CherryPy: The `CherryPy <http://www.cherrypy.org/CherryPy>`_ server requires 3.2.2+
36+
- gevent: The gevent server requires `gevent <http://www.gevent.org/>`_ 0.13.6 or 1.0.0-dev
37+
38+
Testing
39+
-------
40+
41+
ws4py uses the Autobahn functional test suite to ensure it respects the standard. You
42+
must install it to run that test suite against ws4py.
43+
44+
- Autobahn `python <http://autobahn.ws/python>`_
45+
- Autobahn `test suite <http://autobahn.ws/testsuite>`_

docs/servertutorial.rst renamed to docs/sources/servertutorial.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
Server
22
======
33

4+
ws4py comes with a few server implementations built around the main :class:`WebSocket <ws4py.websocket.WebSocket>` class.
5+
46
CherryPy
57
--------
68

@@ -66,8 +68,6 @@ wsgiref
6668
.. code-block:: python
6769
:linenos:
6870
69-
70-
7171
from wsgiref.simple_server import make_server
7272
from ws4py.websocket import EchoWebSocket
7373
from ws4py.server.wsgirefserver import WSGIServer, WebSocketWSGIRequestHandler

docs/ws4py.client.rst renamed to docs/sources/ws4py.client.rst

File renamed without changes.

0 commit comments

Comments
 (0)