Add more examples and expand tutorial in documentation

docs/corpus.rst

@@ -25,13 +25,16 @@ ChatterBot's training module provides methods that allow you to export the
 content of your chat bot's database as a training corpus that can be used to
 train other chat bots.
 
-Here is an example:
-
 .. code-block:: python
 
-   chatbot = ChatBot("Export Example Bot")
+   chatbot = ChatBot('Export Example Bot')
    chatbot.trainer.export_for_training('./export.json')
 
+Here is an example:
+
+.. literalinclude:: ../examples/export_example.py
+   :language: python
+
 .. glossary::
 
    corpus

docs/encoding.rst

@@ -0,0 +1,94 @@
+======================
+Python String Encoding
+======================
+
+The Python developer community has published a great article that covers the
+details of unicode character processing.
+
+- Python 3: https://docs.python.org/3/howto/unicode.html
+- Python 2: https://docs.python.org/2/howto/unicode.html
+
+The following notes are intended to help answer some common questions and issues
+that developers frequently encounter while learning to properly work with different 
+character encodings in Python.
+
+Does ChatterBot handle non-ascii characters?
+============================================
+
+ChatterBot is able to handle unicode values correctly. You can pass it
+non-encoded data and it should be able to process it properly
+(you will need to make sure that you decode the output that is returned).
+
+Bellow is one of ChatterBot's tests from `tests/test_chatbot.py`_,
+this is just a simple check that a unicode response can be processed.
+
+.. code-block:: python
+
+   def test_get_response_unicode(self):
+       """
+       Test the case that a unicode string is passed in.
+       """
+       response = self.chatbot.get_response(u'سلام')
+       self.assertGreater(len(response.text), 0)
+
+This test passes in both Python 2.7 and 3.x. It also verifies that
+ChatterBot *can* take unicode input without issue.
+
+Fixing encoding errors
+======================
+
+When working with string type data in Python, it is possible to encounter errors
+such as the following.
+
+.. code-block:: text
+
+   UnicodeDecodeError: 'utf8' codec can't decode byte 0x92 in position 48: invalid start byte
+
+Depending on what your code looks like, there are a few things that you can do
+to prevent errors like this.
+
+Unicode header
+--------------
+
+.. code-block:: python
+
+   # -*- coding: utf-8 -*-
+
+When to use
++++++++++++
+
+If your strings use escaped unicode characters (they looks like :code:`u'\u00b0C'`) then
+you do not need add the header. If your strings like :code:`'ØÆÅ'` then you are required
+to use the header.
+
+If you are using this header it must be the first line in your Python file.
+
+Unicode escape characters
+-------------------------
+
+.. code-block:: text
+
+   >>> print u'\u0420\u043e\u0441\u0441\u0438\u044f'
+   Россия
+
+When to use
++++++++++++
+
+Prefix your strings with the unicode escape character :code:`u'...'` when you are
+using excaped unicode characters.
+
+Import unicode literals from future
+-----------------------------------
+
+.. code-block:: python
+
+   from __future__ import unicode_literals
+
+When to use
++++++++++++
+
+Use this when you need to make sure that Python 3 code also works in Python 2.
+
+A good article on this can be found here: http://python-future.org/unicode_literals.html
+
+.. _`tests/test_chatbot.py`: https://github.com/gunthercox/ChatterBot/blob/master/tests/test_chatbot.py

docs/examples.rst

@@ -2,8 +2,7 @@
 Examples
 ========
 
-Several simple examples are available to help you get started with ChatterBot.
-Even more examples can be found in the `examples` directory in on GitHub: https://github.com/gunthercox/ChatterBot/tree/master/examples
+The following examples are available to help you get started with ChatterBot.
 
 Simple Example
 ==============
@@ -37,4 +36,29 @@ the `storage_adapter` parameter.
 .. literalinclude:: ../examples/terminal_mongo_example.py
    :language: python
 
+Time and Mathematics Example
+============================
+
+ChatterBot has natural language evaluation capabilities that
+allow it to process and evaluate mathematical and time-based
+inputs.
+
+.. literalinclude:: ../examples/math_and_time.py
+   :language: python
+
+Gitter Example
+==============
+
+ChatterBot works great with chat rooms. An example for the
+popular service *Gitter* demonstrates this.
+
+.. literalinclude:: ../examples/gitter_example.py
+   :language: python
+
+More Examples
+=============
+
+Even more examples can be found in the `examples` directory in on GitHub:
+https://github.com/gunthercox/ChatterBot/tree/master/examples 
+
 .. _install MongoDB: https://docs.mongodb.com/manual/installation/

docs/index.rst

@@ -70,6 +70,7 @@ Contents:
    utils
    django/index
    testing
+   encoding
 
 Report an Issue
 ===============

docs/logic/create-a-logic-adapter.rst

@@ -22,7 +22,7 @@ Example logic adapter
 
    class MyLogicAdapter(LogicAdapter):
        def __init__(self, **kwargs):
-           super(MyLogicAdapter, self).__init__(kwargs)
+           super(MyLogicAdapter, self).__init__(**kwargs)
 
        def can_process(self, statement):
            return True

docs/setup.rst

@@ -1,9 +1,6 @@
-================
-ChatterBot Setup
-================
-
-Installing ChatterBot
-=====================
+============
+Installation
+============
 
 The recommended method for installing ChatterBot is by using `pip`_.
 
@@ -47,4 +44,4 @@ have installed you can run the following command.
 
 .. _git: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
 .. _pip: https://pip.pypa.io/en/stable/installing/
-.. _PyPi: https://pypi.python.org/pypi
+.. _PyPi: https://pypi.python.org/pypi

docs/tutorial.rst

@@ -2,13 +2,24 @@
 ChatterBot Tutorial
 ===================
 
+This tutorial will guide you through the process of creating a simple command-line chat bot using ChatterBot.
+
+Getting help
+============
+
+If you’re having trouble with this tutorial, you can post a message on Gitter_
+to chat with other ChatterBot users who might be able to help.
+
+If you believe that you have encountered an error in ChatterBot, please open a
+ticket on GitHub: https://github.com/gunthercox/ChatterBot/issues/new
+
 Creating your first chat bot
 ============================
 
 Create a new file named `chatbot.py`.
 Then open `chatbot.py` in your editor of choice.
 
-Before we do anything, ChatterBot needs to be imported.
+Before we do anything else, ChatterBot needs to be imported.
 The import for ChatterBot should look like the following line.
 
 .. code-block:: python
@@ -51,9 +62,9 @@ if it does not already exist.
 .. code-block:: python
 
    bot = ChatBot(
-       "Norman",
-       storage_adapter="chatterbot.storage.JsonFileStorageAdapter",
-       database="./database.json"
+       'Norman',
+       storage_adapter='chatterbot.storage.JsonFileStorageAdapter',
+       database='./database.json'
    )
 
 .. note::
@@ -72,11 +83,11 @@ the terminal. The output terminal adapter print's the chat bot's response.
 .. code-block:: python
 
    bot = ChatBot(
-       "Norman",
-       storage_adapter="chatterbot.storage.JsonFileStorageAdapter",
-       input_adapter="chatterbot.input.TerminalAdapter",
-       output_adapter="chatterbot.output.TerminalAdapter",
-       database="./database.json"
+       'Norman',
+       storage_adapter='chatterbot.storage.JsonFileStorageAdapter',
+       input_adapter='chatterbot.input.TerminalAdapter',
+       output_adapter='chatterbot.output.TerminalAdapter',
+       database='./database.json'
    )
 
 Logic adapters
@@ -95,15 +106,15 @@ operations.
 .. code-block:: python
 
    bot = ChatBot(
-       "Norman",
-       storage_adapter="chatterbot.storage.JsonFileStorageAdapter",
-       input_adapter="chatterbot.input.TerminalAdapter",
-       output_adapter="chatterbot.output.TerminalAdapter",
+       'Norman',
+       storage_adapter='chatterbot.storage.JsonFileStorageAdapter',
+       input_adapter='chatterbot.input.TerminalAdapter',
+       output_adapter='chatterbot.output.TerminalAdapter',
        logic_adapters=[
-           "chatterbot.logic.MathematicalEvaluation",
-           "chatterbot.logic.TimeLogicAdapter"
+           'chatterbot.logic.MathematicalEvaluation',
+           'chatterbot.logic.TimeLogicAdapter'
        ],
-       database="./database.json"
+       database='./database.json'
    )
 
 Getting a response
@@ -122,7 +133,32 @@ we can exit the loop and stop the program when a user enters `ctrl+c`.
        except(KeyboardInterrupt, EOFError, SystemExit):
            break
 
+Training your chat bot
+----------------------
+
+At this point your chat bot, Norman will learn to communicate as you talk to him.
+You can speed up this process by training him with examples of existing conversations.
+
+.. code-block:: python
+
+   bot.train([
+       'How are you?',
+       'I am good.',
+       'That is good to hear.',
+       'Thank you',
+       'You are welcome.',
+   ])
+
+You can run the training process multiple times to reinforce prefered responses
+to particular input statements. You can also run the train command on a number
+of different example dialogs to increase the breadth of inputs that your chat
+bot can respond to.
+
+---- 
+
 This concludes this ChatterBot tutorial. Please see other sections of the
 documentation for more details and examples.
 
-Next: See :doc:`./examples`
+Up next: :doc:`./examples`
+
+.. _Gitter: https://gitter.im/chatter_bot/Lobby

examples/export_example.py

@@ -15,4 +15,4 @@
 chatbot.train('chatterbot.corpus.english')
 
 # Now we can export the data to a file
-chatbot.trainer.export_for_training('./myfile.json')
+chatbot.trainer.export_for_training('./my_export.json')