Merge branch 'release/v0.3.4'

.gitignore

@@ -38,4 +38,8 @@ nosetests.xml
 .idea
 
 #Sphinx
-docs/_
+docs/_
+
+#VirtualEnv
+.Python
+include/

docs/changelog.rst

@@ -0,0 +1,27 @@
+Changelog
+=============
+
+Version 0.3.4
+----------------
++ Rename ``WeRoBot.app`` to ``WeRoBot.wsgi``
++ Add ``BaseRoBot`` class. It's useful for creating extensions.
++ Reorganized documents.
+
+Version 0.3.3
+----------------
++ Add ``host`` param in werobot.run
++ Update EventMessage
++ Add LinkMessage
+
+Version 0.3.2
+----------------
++ Convert all arguments to unicode in Python 2 ( See issue `#1 <https://github.com/whtsky/WeRoBot/pull/1>`_ )
+
+Version 0.3.1
+----------------
++ Add ``server`` param in werobot.run
+
+Version 0.3.0
+----------------
+
++ Add new messages and replies support for WeChat 4.5

docs/deploy.rst

@@ -0,0 +1,89 @@
+部署
+=====================
+
+在独立服务器上部署
+----------------------
+当你运行 `werobot.run` 的时候，你可以通过传递 `server` 参数来手动指定使用的服务器 ::
+
+    import werobot
+
+    robot = werobot.WeRoBot(token='tokenhere')
+
+    @robot.handler
+    def echo(message):
+        return 'Hello World!'
+
+    robot.run(server='tornado')
+
+server 支持以下几种：
+
++ cgi
++ flup
++ wsgiref
++ waitress
++ cherrypy
++ paste
++ fapws3
++ tornado
++ gae
++ twisted
++ diesel
++ meinheld
++ gunicorn
++ eventlet
++ gevent
++ rocket
++ bjoern
++ auto
+
+当 server 为 auto 时， WeRoBot 会自动依次尝试以下几种服务器：
+
++ Waitress
++ Paste
++ Twisted
++ CherryPy
++ WSGIRef
+
+所以，只要你安装了相应的服务器软件，就可以使用 ``werobot.run`` 直接跑在生产环境下。
+
+.. note:: server 的默认值为 ``auto``
+
+使用 Supervisor 管理守护进程
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+请注意， ``werobot.run`` 是跑在 **非守护进程模式下** 的——也就是说，一旦你关闭终端，进程就会自动退出。
+
+我们建议您使用 `Supervisor <http://supervisord.org/>`_ 来管理 WeRoBot 的进程。
+
+配置文件样例： ::
+
+    [program:wechat_robot]
+    command = python /home/whtsky/robot.py
+    user = whtsky
+    redirect_stderr = true
+    stdout_logfile = /home/whtsky/logs/robot.log
+
+使用 Nginx 进行反向代理
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+微信服务器只支持80端口的机器人——显然，你的服务器上不会只跑着一个微信机器人。对于这种情况，我们建议您使用 Nginx 来进行反向代理。
+
+配置文件样例： ::
+
+    server {
+        server_name example.com;
+        listen 80;
+
+        location / {
+            proxy_pass_header Server;
+            proxy_redirect off;
+            proxy_pass http://127.0.0.1:8888;
+        }
+    }
+
+.. note:: 在这个例子中， WeRoBot 的端口号为8888。你应该在微信管理后台中将服务器地址设为 ``http://example.com`` 。
+
+在SAE上部署
+-----------------
+
+参考： `示例仓库 <https://github.com/whtsky/WeRoBot-SAE-demo>`_

docs/filters.rst

@@ -0,0 +1,70 @@
+类型过滤
+=================
+
+在大多数情况下， 一个 Handler 并不能处理所有类型的消息。幸运的是， WeRoBot 可以帮你过滤收到的消息。
+
+只想处理被新用户关注的消息？::
+
+    import werobot
+
+    robot = werobot.WeRoBot(token='tokenhere')
+
+    @robot.subscribe
+    def subscribe(message):
+        return 'Hello My Friend!'
+
+    robot.run()
+
+或者，你的 handler 只能处理文本？ ::
+
+    import werobot
+
+    robot = werobot.WeRoBot(token='tokenhere')
+
+    @robot.text
+    def echo(message):
+        return message.content
+
+    robot.run()
+
+==================  ===========
+修饰符                类型
+==================  ===========
+robot.text           文本
+robot.image          图像
+robot.location       位置
+robot.subscribe      被关注
+robot.unsubscribe    被取消关注
+robot.link           链接
+robot.unknown        未知类型
+==================  ===========
+
+额，这个 handler 想处理文本信息和地理位置信息？ ::
+
+    import werobot
+
+    robot = werobot.WeRoBot(token='tokenhere')
+
+    @robot.text
+    @robot.location
+    def handler(message):
+        # Do what you love to do
+        pass
+
+    robot.run()
+
+当然，你也可以用 `add_handler` 函数添加handler，就像这样::
+
+    import werobot
+
+    robot = werobot.WeRoBot(token='tokenhere')
+
+    def handler(message):
+        # Do what you love to do
+        pass
+
+    robot.add_handler(handler, types=['text', 'location'])
+
+    robot.run()
+
+.. note:: 通过 `robot.handler` 添加的 handler 将收到所有信息。

docs/handlers.rst

@@ -0,0 +1,24 @@
+Handlers
+==========
+
+
+WeRoBot会将合法的请求发送给handlers依次执行。
+
+如果某一个Handler返回了非空值，WeRoBot就会根据这个值创建回复，后面的handlers将不会被执行。
+
+你可以通过两种方式添加handler ::
+
+    import werobot
+
+    robot = werobot.WeRoBot(token='tokenhere')
+
+    # 通过修饰符添加handler
+    @robot.handler
+    def echo(message):
+        return 'Hello World!'
+
+    # 通过`add_handler`添加handler
+    def echo(message):
+        return 'Hello World!'
+    robot.add_handler(echo)
+