Updating docstrings and documentation.

Author: hayesall

Diff for: docs/source/index.rst

@@ -3,18 +3,102 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to rnlp's documentation!
-================================
+``rnlp``
+========
+
+  *Relational NLP Preprocessing*: A Python package and tool for converting text
+  into a set of relational facts.
+
+  :Authors:
+    Kaushik Roy (`@kkroy36 <https://github.com/kkroy36/>`_), Alexander L. Hayes (`@batflyer <https://github.com/batflyer/>`_)
+
+  :Index: :ref:`genindex`
+  :Modules: :ref:`modindex`
+  :Source: `GitHub <https://github.com/starling-lab/rnlp>`_
+  :Bugtracker: `GitHub Issues <https://github.com/starling-lab/rnlp/issues/>`_
+
+  .. image:: https://img.shields.io/pypi/pyversions/rnlp.svg?style=flat-square
+  .. image:: https://img.shields.io/pypi/v/rnlp.svg?style=flat-square
+  .. image:: https://img.shields.io/pypi/l/rnlp.svg?style=flat-square
+  .. image:: https://img.shields.io/readthedocs/rnlp/stable.svg?flat-square
+	   :target: http://rnlp.readthedocs.io/en/stable/
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
+Installation
+------------
+
+Stable builds on PyPi
+
+.. code-block:: bash
+
+		pip install rnlp
+
+Development builds on GitHub
+
+.. code-block:: bash
+
+		pip install git+git://github.com/starling-lab/rnlp.git
+
+Quick-Start
+-----------
+
+``rnlp`` can be used either as a CLI tool or as an imported Python Package.
+
++---------------------------------------+--------------------------------------+
+| **CLI**                               | **Imported**                         |
++---------------------------------------+--------------------------------------+
+|.. code-block:: bash                   |.. code-block:: python                |
+|                                       |                                      |
+|  $ python -m rnlp -f files/doi.txt    |  from rnlp.corpus import declaration |
+|                                       |  import rnlp                         |
+|                                       |                                      |
+|                                       |  doi = declaration()                 |
+|                                       |  rnlp.converter(doi)                 |
++---------------------------------------+--------------------------------------+
+
+Text will be converted into relational facts, relations encoded are:
+
+- between blocks of size 'n' (i.e. 2 sentences) in the blocks.
+
+- between block's of size n (i.e. 'n' sentences) and sentences in the blocks.
+
+- between sentences and words in the sentences.
+
+---
+
+The relationships currently encoded are:
+
+1. earlySentenceInBlock - sentence occurs within a third of the block length
+
+2. earlyWordInSentence - word occurs within a third of the sentence length
+
+3. lateSentenceInBlock - sentence occurs after two-thirds of the block length
+
+4. midWayWordInSentence - word occurs between a third and two-thirds of the block length
+
+5. nextSentenceInBlock - sentence that follows a sentence in a block
+
+6. nextWordInSentence - word that follows a word in a sentence in a block
+
+7. sentenceInBlock - sentence occurs in a block
+
+8. wordInSentence - word occurs in a sentence.
+
+9. wordString - the string contained in the word.
+
+10. partOfSpeech - the part of speech of the word.
+
+---
+
+Files contain a toy corpus (``files/``) and an image of a BoostSRL tree for predicting if a word in a sentence is the word "you".
 
+.. image:: https://raw.githubusercontent.com/starling-lab/rnlp/master/docs/img/output.png
 
-Indices and tables
-==================
+The tree says that if the word string contained in word 'b' is "you" then 'b' is the word "you". (This is of course true).
+A more interesting inference is the False branch that says that if word 'b' is an early word in sentence 'a' and word 'anon12035' is also an early word in sentence 'a' and if the word string contained in word 'anon12035' is "Thank", then the word 'b' has decent change of being the word "you". (The model was able to learn that the word "you" often occurs with the word "Thank" in the same sentence when "Thank" appears early in that sentence).
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+ .. _`@kkroy36`: https://github.com/kkroy36/
+ .. _`@batflyer`: https://github.com/batflyer/

Diff for: docs/source/rnlp.rst

@@ -12,14 +12,21 @@ rnlp\.corpus module
     :undoc-members:
     :show-inheritance:
 
-rnlp\.parseInputCorpus module
+rnlp\.parse module
 -----------------------------
 
 .. automodule:: rnlp.parse
     :members:
     :undoc-members:
     :show-inheritance:
 
+rnlp\.textprocessing module
+-----------------------------
+
+.. automodule:: rnlp.textprocessing
+    :members:
+    :undoc-members:
+    :show-inheritance:
 
 Module contents
 ---------------

Diff for: rnlp/__init__.py

@@ -75,7 +75,9 @@
 ]
 
 from . import parse
-from . import textprocessing
+
+from .textprocessing import getBlocks
+from .textprocessing import getSentences
 
 def converter(input_string, block_size=2):
     """

Diff for: rnlp/corpus.py

@@ -14,33 +14,64 @@
 # along with this program (at the base of this repository). If not,
 # see <http://www.gnu.org/licenses/>
 
+"""
+rnlp.corpus
+-----------
+
+Built-in corpus and utilities for reading corpora from files.
+
+.. code-block:: python
+
+                # rnlp.corpus is not imported by default.
+                import rnlp.corpus
+"""
+
 from os import listdir
 from tqdm  import tqdm
 
-def readCorpus(file):
+def readCorpus(location):
     """
     Returns the contents of a file or a group of files as a string.
 
-    :param file: .txt file or a directory to read files from.
-    :type file: str.
+    :param location: .txt file or a directory to read files from.
+    :type location: str.
 
     :returns: A string of all contents joined together.
     :rtype: str.
+
+    .. note::
+
+        This function takes a ``location`` on disk as a parameter. Location is
+        assumed to be a string representing a text file or a directory. A text
+        file is further assumed to contain ``.txt`` as a file extension while
+        a directory may be a path.
+
+    Example:
+
+    .. code-block:: python
+
+                    from rnlp.corpus import readCorpus
+
+                    # If you have a text file:
+                    doi = readCorpus('files/doi.txt')
+
+                    # If you have multiple files to read from:
+                    corpus = readCorpus('files')
     """
     print("Reading corpus from file(s)...")
 
     corpus = ''
 
-    if '.txt' in file:
-        with open(file) as fp:
+    if '.txt' in location:
+        with open(location) as fp:
             corpus = fp.read()
     else:
 
-        dirFiles = listdir(file)
+        dirFiles = listdir(location)
         nFiles = len(dirFiles)
 
         for f in tqdm(dirFiles):
-            with open(file+"/"+f) as fp:
+            with open(location+"/"+f) as fp:
                 corpus += fp.read()
 
     return corpus