Updated documentation.

This update adds details for logic adapters, information about Statement and Response objects, and details about the main ChatBot class.
gunthercox · May 12, 2016 · fc4cd27 · fc4cd27
1 parent 07f8880
commit fc4cd27
Show file tree

Hide file tree

Showing 5 changed files with 144 additions and 3 deletions.
diff --git a/.gitignore b/.gitignore
@@ -3,8 +3,12 @@ build
 dist
 include
 lib
-database.db
-settings.py
 *.pyc
 *.swp
 *.egg-info
+
+database.db
+settings.py
+
+# Sphinx docs
+docs/_build/
diff --git a/docs/adapters/logic.rst b/docs/adapters/logic.rst
@@ -1,4 +1,119 @@
 Logic Adapters
 ==============
 
+Logic adapters determine the logic for how ChatterBot selects a responses to a given input statement.
+
+The logic adapter that your bot uses can be specified by setting the `logic_adapters` parameter to the import path of the logic adapter you want to use.
+
+It is possible to enter any number of logic adapters for your bot to use.
+If multiple adapters are used, then the bot will return the response with
+the highest calculated confidence value. If multiple adapters return the
+same confidence, then the adapter that is entered into the list first will
+take priority.
+
+.. code-block:: python
+
+   chatbot = ChatBot(
+       "My ChatterBot",
+       logic_adapters=[
+           "chatterbot.adapters.logic.ClosestMatchAdapter"
+       ]
+   )
+
+Closest Match Adapter
+---------------------
+
+.. autofunction:: chatterbot.adapters.logic.ClosestMatchAdapter
+
+The `ClosestMatchAdapter` selects a response based on the closest know match to a given statement.
+
+How it works
+++++++++++++
+
+The closest match algorithm determines the similarity between the input statement and a set of known statements. For example, there is a 65% similarity between the statements _"where is the post office?"_ and _"looking for the post office"_. The closest match algorithm selects the highest matching known statements and returns a response based on that selection.
+
+Closest Meaning Adapter
+-----------------------
+
+.. autofunction:: chatterbot.adapters.logic.ClosestMeaningAdapter
+
+The `ClosestMeaningAdapter` selects a response based on how closely two statements match each other based on the closeness of the synsets of each word in the word matrix formed by both sentences.
+
+How it works
+++++++++++++
+
+The closest meaning algorithm uses the [wordnet](http://www.nltk.org/howto/wordnet.html) functionality of [nltk](www.nltk.org) to determine the similarity of two statements based on the path similarity between each token of each statement. This is essentially an evaluation of the closeness of synonyms. The statement that has the closest path similarity of synsets to the input statement is returned.
+
+Time Logic Adapter
+------------------
+
+.. autofunction:: chatterbot.adapters.logic.TimeLogicAdapter
+
+The `TimeLogicAdapter` identifies statements in which a question about the current time is asked.
+If a matching question is detected, then a response containing the current time is returned.
+
+Example
++++++++
+
+| User: What time is it?
+| Bot: The current time is 4:45PM.  
+
+Mathematical Evaluation Adapter
+---------------------------------
+
+.. autofunction:: chatterbot.adapters.logic.MathematicalEvaluation
+
+The `MathematicalEvaluation` logic adapter checks a given statement to see if
+it contains a mathematical expression that can be evaluated. If one exists,
+then it returns a response containing the result.
+This adapter is able to handle any combination of word and numeric operators.
+
+Example
++++++++
+
+| User: What is four plus four?  
+| Bot: (4 + 4) = 8
+
+Creating a new logic adapter
+----------------------------
+
+You can write your own logic adapters by creating a new class that
+inherits from `LogicAdapter` and overides the overrides necessary
+methods established in the base `LogicAdapter` class.
+
 .. autofunction:: chatterbot.adapters.logic.LogicAdapter
+
+.. code-block:: python
+
+   from chatterbot.adapters.logic import LogicAdapter
+
+   class MyLogicAdapter(LogicAdapter):
+       def __init__(self, **kwargs):
+           """
+           The __init__ method is optional.
+           If you need to access any of the kwargs that were
+           passed into the ChatBot constructor this is where
+           you can do so.
+
+           (An API key might be an example of a parameter
+           you would want to access here.)
+           """
+
+       def can_process(self, statement):
+           """
+           This is a preliminary method that can be used to
+           check the input statement to see if a value can
+           possibly be returned when it is evaluated using
+           the adapter's process method.
+
+           This method returns true by default.
+           """
+           return True
+
+       def process(self, statement):
+           """
+           This method will receive the input statement.
+           Establish custom response selection logic here.
+           """
+           return selected_statement
+
diff --git a/docs/adapters/storage.rst b/docs/adapters/storage.rst
@@ -14,7 +14,7 @@ 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.

diff --git a/docs/chatterbot.rst b/docs/chatterbot.rst
@@ -2,3 +2,17 @@ ChatterBot
 ==========
 
 .. autofunction:: chatterbot.ChatBot
+
+The main class :code:`ChatBot` is a connecting point between each of
+ChatterBot's adapters. In this class, an input statement is returned
+from the input adapter, processed and stored by the logic and storage
+adapters, and then passed to the output adapter to be returned to the
+user.
+
+Getting a response
+------------------
+
+The method that is used to get a response to a given input
+is :code:`get_response()`. This method takes an input value
+which the chat bot's input adapter then converts into a
+statement object before processing it.
diff --git a/docs/conversations.rst b/docs/conversations.rst
@@ -6,7 +6,15 @@ Statements
 
 .. autofunction:: chatterbot.conversation.Statement
 
+ChatterBot's statement objects represent either an input statement that the
+chat bot has recieved from a user, or an output statement that the chat bot
+has returned based on some input.
+
 Responses
 ---------
 
 .. autofunction:: chatterbot.conversation.Response
+
+ChatterBot's response objects represent the relationship between two
+statements. A response indicates that one statements was issued in
+response to another statement.
-Original file line number
+Diff line change
@@ Expand Up @@
        )
     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.
@@ Expand Down @@