move documents from semi-automated rst files to correct code positions

.gitignore

@@ -16,6 +16,7 @@ outputs/
 
 # Sphinx documentation
 docs/_build/
+docs/source/modules.rst
 
 # Packaging
 *.egg-info/

docs/conf.py

@@ -13,7 +13,7 @@
 import os
 import sys
 
-sys.path.insert(0, os.path.abspath("../textattack/"))
+sys.path.insert(0, os.path.abspath("../"))
 
 # -- Project information -----------------------------------------------------
 project = "TextAttack"
@@ -34,6 +34,7 @@ master_doc = "index"
 extensions = [
     "sphinx.ext.viewcode",
     "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
     "sphinx.ext.napoleon",
     "sphinx_rtd_theme",
     # Enable .ipynb doc files

docs/index.rst

@@ -10,7 +10,7 @@
    1start/references.md
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
    :caption: Get Started
 
    Installation <1start/installation>
@@ -31,12 +31,12 @@
    
 
 .. toctree::
-   :maxdepth: 3
+   :maxdepth: 5
    :glob:
    :caption: Developer Guide
    
    1start/support.md
    1start/api-design-tips.md
-   api/index.rst
-   source/textattack.rst
+   api/index
+   source/textattack
    

docs/source/modules.rst

@@ -1,12 +0,0 @@
-textattack
-==========
-
-.. toctree::
-   :maxdepth: 4
-
-   textattack
-
-
-
-.. autosummary::
-   :toctree: _autosummary

textattack/attack_recipes/attack_recipe.py

@@ -1,3 +1,19 @@
+"""
+We provide a number of pre-built attack recipes, which correspond to attacks from the literature. To run an attack recipe from the command line, run::
+
+    textattack attack --recipe [recipe_name]
+
+To initialize an attack in Python script, use::
+
+    <recipe name>.build(model_wrapper)
+
+For example, ``attack = InputReductionFeng2018.build(model)`` creates `attack`, an object of type ``Attack`` with the goal function, transformation, constraints, and search method specified in that paper. This object can then be used just like any other attack; for example, by calling ``attack.attack_dataset``.
+
+TextAttack supports the following attack recipes (each recipe's documentation contains a link to the corresponding paper): 
+
+.. contents:: :local:
+"""
+
 from abc import ABC, abstractmethod
 
 from textattack.shared import Attack

textattack/attack_results/attack_result.py

@@ -1,3 +1,8 @@
+"""
+The result of an attack's attempt to find a successful adversarial perturbation. 
+
+"""
+
 from abc import ABC
 
 from textattack.goal_function_results import GoalFunctionResult

textattack/augmentation/augmenter.py

@@ -1,3 +1,7 @@
+"""
+Transformations and constraints can be used outside of an attack for simple NLP data augmentation with the ``Augmenter`` class that returns all possible transformations for a given string.
+
+"""
 import random
 
 import tqdm

textattack/augmentation/recipes.py

@@ -1,3 +1,7 @@
+"""
+Transformations and constraints can be used for simple NLP data augmentations. Here is a list of recipes for NLP data augmentations
+
+"""
 import random
 
 import textattack

textattack/constraints/constraint.py

@@ -1,3 +1,19 @@
+"""
+Constraints determine whether a given transformation is valid. Since transformations do not perfectly preserve semantics semantics or grammaticality, constraints can increase the likelihood that the resulting transformation preserves these qualities. All constraints are subclasses of the ``Constraint`` abstract class, and must implement at least one of ``__call__`` or ``call_many``. 
+
+We split constraints into three main categories.
+
+   :ref:`Semantics`: Based on the meaning of the input and perturbation.
+
+   :ref:`Grammaticality`: Based on syntactic properties like part-of-speech and grammar.
+   
+   :ref:`Overlap`: Based on character-based properties, like edit distance.
+
+A fourth type of constraint restricts the search method from exploring certain parts of the search space:
+
+   :ref:`pre_transformation`: Based on the input and index of word replacement.
+"""
+
 from abc import ABC, abstractmethod
 
 import textattack

textattack/shared/attack.py

@@ -1,3 +1,13 @@
+"""TextAttack builds attacks from four components:
+
+- `Goal Functions <../attacks/goal_function.html>`__ stipulate the goal of the attack, like to change the prediction score of a classification model, or to change all of the words in a translation output.
+- `Constraints <../attacks/constraint.html>`__ determine if a potential perturbation is valid with respect to the original input.
+- `Transformations <../attacks/transformation.html>`__ take a text input and transform it by inserting and deleting characters, words, and/or phrases.
+- `Search Methods <../attacks/search_method.html>`__ explore the space of possible **transformations** within the defined **constraints** and attempt to find a successful perturbation which satisfies the **goal function**.
+
+The ``Attack`` class represents an adversarial attack composed of a goal function, search method, transformation, and constraints.
+"""
+
 from collections import deque
 
 import lru