Updated examples and documentation.

This adds a tutorial on how to use the MongoDB adapter.
This also adds information about training a chat bot.

.travis.yml

@@ -3,7 +3,6 @@ language: python
 
 python:
   - '3.4'
-  - '3.3'
   - '2.7'
 
 install:

chatterbot/adapters/logic/no_logic.py

@@ -0,0 +1,21 @@
+from chatterbot.adapters.logic import LogicAdapter
+from chatterbot.conversation import Statement
+
+
+class NoLogic(LogicAdapter):
+
+    def can_process(self, statement):
+        """
+        Determines if this adapter can respond to the input.
+        """
+        return True
+
+    def process(self, statement):
+        import random
+
+        # Get all statements that are in response to the closest match
+        response_list = self.context.storage.filter(
+            in_response_to__contains=statement.text
+        )
+
+        return 1, random.choice(response_list)

docs/adapters/index.rst

@@ -1,3 +1,4 @@
+========
 Adapters
 ========
 
@@ -41,4 +42,12 @@ Each adapter can be set by passing in the dot-notated import path to the constru
        ],
    )
 
+Third Party Adapters
+--------------------
+
+`chatterbot-voice`_ - A text to speech (tts) and speech recognition adapter designed to use with ChatterBot.
+`chatterbot-weather`_ A ChatterBot logic adapter that returns information about the current weather.
+
 .. _MongoDB: https://docs.mongodb.com/
+.. _chatterbot-voice: https://github.com/gunthercox/chatterbot-voice
+.. _chatterbot-weather: https://github.com/gunthercox/chatterbot-weather

docs/adapters/input.rst

@@ -1,3 +1,4 @@
+==============
 Input Adapters
 ==============
 

docs/adapters/logic.rst

@@ -1,3 +1,4 @@
+==============
 Logic Adapters
 ==============
 

docs/adapters/output.rst

@@ -1,3 +1,4 @@
+===============
 Output Adapters
 ===============
 

docs/adapters/storage.rst

@@ -1,3 +1,4 @@
+================
 Storage Adapters
 ================
 
@@ -14,14 +15,14 @@ The storage adapter that your bot uses can be specified by setting the `storage_
    )
 
 Read Only Mode
---------------
+==============
 
 If you instantiate your chatterbot with the parameter `read_only=True`
 then the database will not be altered when input is given to the chatterbot.
 The `read_only` parameter is set to false by default.
 
 Json Database Adapter
----------------------
+=====================
 
 .. autofunction:: chatterbot.adapters.storage.JsonDatabaseAdapter
 
@@ -32,18 +33,35 @@ passed to the ChatterBot constructor. This storage adapter uses a local file
 database so this parameter is needed to specify the location of the file.
 
 Mongo Database Adapter
-----------------------
+======================
 
 .. autofunction:: chatterbot.adapters.storage.MongoDatabaseAdapter
 
 "chatterbot.adapters.storage.MongoDatabaseAdapter"
 
-The MongoDB Database adapter requires an additional parameter (`database`) to
-be passed to the ChatterBot constructor. This value will be the name of the
-database you choose to connect to.
+database
+--------
+
+The MongoDB Database adapter requires an additional parameter, `database`,
+to be passed to the ChatterBot constructor. This value will be the name
+of the database you choose to connect to.
+
+.. code-block:: python
+
+   database='chatterbot-database'
+
+database_uri
+------------
+
+If you need to connect to a remote instance of MongoDB, you
+can set the `database_uri` parameter to the uri of your database.
+
+.. code-block:: python
+
+   database_uri='mongodb://example.com:8100/'
 
 Creating a new storage adapter
-------------------------------
+==============================
 
 It is fairly easy to write your own storage adapter to connect to just about
 any database or storage endpoint. To get started, you will need to create a

docs/conf.py

@@ -9,6 +9,17 @@
 import sys
 import os
 
+# Get the project root dir, which is the parent dir of this
+cwd = os.getcwd()
+project_root = os.path.dirname(cwd)
+
+# Insert the project root dir as the first element in the PYTHONPATH.
+# This lets us ensure that the source package is imported, and that its
+# version is used.
+sys.path.insert(0, project_root)
+
+import chatterbot
+
 # 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.
@@ -55,9 +66,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = u'0.4'
+version = chatterbot.__version__
 # The full version, including alpha/beta/rc tags.
-release = u'0.4.0'
+release = chatterbot.__version__
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -109,7 +120,7 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'alabaster'
+#html_theme = 'alabaster'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the

docs/examples.rst

@@ -22,3 +22,21 @@ output adapters have been specified.
 
 .. literalinclude:: ../examples/terminal_example2.py
    :language: python
+
+Using MongoDB
+-------------
+
+Before you can use ChatterBot's built in adapter for MongoDB,
+you will need to `install MongoDB`_. Make sure MongoDB is
+running in your environment before you execute your program.
+To tell ChatterBot to use this adapter, you will need to set
+the `storage_adapter` parameter.
+
+.. code-block:: python
+
+   storage_adapter="chatterbot.adapters.storage.MongoDatabaseAdapter"
+
+.. literalinclude:: ../examples/terminal_mongo_example.py
+   :language: python
+
+.. _install MongoDB: https://docs.mongodb.com/manual/installation/

docs/index.rst

@@ -10,10 +10,10 @@ Contents:
 
    tutorial
    examples
-   chatterbot
+   training
    adapters/index
+   chatterbot
    conversations
-   corpus
    utils
 
 About ChatterBot
@@ -30,6 +30,11 @@ Simple Example
 .. literalinclude:: ../examples/basic_example.py
    :language: python
 
+Report an Issue
+===============
+
+Please direct all bug reports and feature requests to the project's issue
+tracker on `GitHub`_.
 
 Indices and tables
 ==================
@@ -38,3 +43,4 @@ Indices and tables
 * :ref:`modindex`
 * :ref:`search`
 
+.. _GitHub: https://github.com/gunthercox/ChatterBot

docs/training.rst

@@ -0,0 +1,95 @@
+========
+Training
+========
+
+ChatterBot has tools that simplify the process of training a bot instance.
+These tools range from simple utility methods that update relations of known
+statements, to a corpus of pre-loaded training data that you can use.
+
+Training via list data
+======================
+
+For the training, process, you will need to pass in a list of statements where the order of each statement is based on it's placement in a given conversation.
+
+For example, if you were to run bot of the following training calls, then the resulting chatterbot would respond to both statements of "Hi there!" and "Greetings!" by saying "Hello".
+
+.. code-block:: python
+
+   chatterbot = ChatBot("Training Example")
+
+   chatterbot.train([
+       "Hi there!",
+       "Hello",
+   ])
+
+   chatterbot.train([
+       "Greetings!",
+       "Hello",
+   ])
+
+You can also provide longer lists of training conversations.
+This will establish each item in the list as a possible response to it's predecessor in the list.
+
+.. code-block:: python
+
+   chatterbot.train([
+       "How are you?",
+       "I am good.",
+       "That is good to hear.",
+       "Thank you",
+       "You are welcome.",
+   ])
+
+Training with corpus data
+=========================
+
+ChatterBot comes with a corpus data and utility module that makes it easy to
+quickly train your bot to communicate. To do so, simply specify the corpus
+data modules you want to use.
+
+.. code-block:: python
+
+   chatterbot.train(
+       "chatterbot.corpus.english"
+   )
+
+Specifying corpus scope
+-----------------------
+
+It is also possible to import individual subsets of ChatterBot's at once.
+For example, if you only wish to train based on the english greetings and
+conversations corpora then you would simply specify them.
+
+.. code-block:: python
+
+   chatterbot.train(
+       "chatterbot.corpus.english.greetings",
+       "chatterbot.corpus.english.conversations"
+   )
+
+The ChatterBot Corpus
+=====================
+
+This is a :term:`corpus` of data that is included in the chatterbot module.
+
+Corpus language availability
+----------------------------
+
+Corpus data is user contributed, but it is also not difficult to create one if you are familiar with the language.
+This is because each corpus is just a sample of various input statements and their responses for the bot to train itself with.
+
+To explore what languages and sets of corpora are available, check out the `chatterbot/corpus/data`_ directory in the repository.
+
+If you are interested in contributing a new language corpus, or adding a module to an existing language, please create a pull request. Contributions are welcomed!
+
+.. glossary::
+
+   corpus
+      In linguistics, a corpus (plural corpora) or text corpus is a large
+      and structured set of texts. They are used to do statistical analysis
+      and hypothesis testing, checking occurrences or validating linguistic
+      rules within a specific language territory [1]_.
+
+.. [1] https://en.wikipedia.org/wiki/Text_corpus
+
+.. _chatterbot/corpus/data: https://github.com/gunthercox/ChatterBot/tree/master/chatterbot/corpus

examples/terminal_example.py

@@ -1,10 +1,5 @@
 from chatterbot import ChatBot
 
-'''
-In this example we use a while loop combined with a try-except statement.
-This allows us to have a conversation with the chat bot until we press
-ctrl-c or ctrl-d on the keyboard.
-'''
 
 # Create a new instance of a ChatBot
 bot = ChatBot("Terminal",
@@ -19,16 +14,15 @@
     database="../database.db"
 )
 
-# Text to prompt the user with initially
-user_input = "Type something to begin..."
-
-print(user_input)
+print("Type something to begin...")
 
+# The following loop will execute each time the user enters input
 while True:
     try:
-        # We pass None to this method because it expects a response.
-        # The TerminalAdapter will handle reading from the user's terminal.
+        # We pass None to this method because the parameter
+        # is not used by the TerminalAdapter
         bot_input = bot.get_response(None)
 
+    # Press ctrl-c or ctrl-d on the keyboard to exit
     except (KeyboardInterrupt, EOFError, SystemExit):
         break

examples/terminal_example2.py

@@ -18,5 +18,6 @@
         bot_input = bot.get_response(None)
         print(bot_input)
 
+    # Press ctrl-c or ctrl-d on the keyboard to exit
     except (KeyboardInterrupt, EOFError, SystemExit):
         break

examples/terminal_mongo_example.py

@@ -1,7 +1,7 @@
 from chatterbot import ChatBot
 
 
-# Create a new instance of a ChatBot
+# Create a new ChatBot instance
 bot = ChatBot("Terminal",
     storage_adapter="chatterbot.adapters.storage.MongoDatabaseAdapter",
     logic_adapters=[
@@ -14,20 +14,10 @@
 
 print("Type something to begin...")
 
-'''
-In this example we use a while loop combined with a try-except statement.
-This allows us to have a conversation with the chat bot until we press
-ctrl-c or ctrl-d on the keyboard.
-'''
-
 while True:
     try:
-        '''
-        The get_response method also uses the io adapter to determine how
-        the bot's output should be returned. In the case of the TerminalAdapter,
-        the output is printed to the user's terminal.
-        '''
         bot_input = bot.get_response(None)
 
+    # Press ctrl-c or ctrl-d on the keyboard to exit
     except (KeyboardInterrupt, EOFError, SystemExit):
         break