Auto-generate API documentation. Refactor code.

docs/api.rst

@@ -0,0 +1,10 @@
+API Documentation
+=================
+
+This is a complete list of available methods, along with details about them.
+
+:mod:`fauxfactory`
+------------------
+
+.. automodule:: fauxfactory
+    :members:

docs/conf.py

@@ -18,7 +18,13 @@
 # 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.
-#sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(
+    0,
+    os.path.realpath(os.path.join(
+        os.path.dirname(__file__),
+        os.path.pardir
+    ))
+)
 
 # -- General configuration ------------------------------------------------
 
@@ -97,6 +103,21 @@
 # If true, keep warnings as "system message" paragraphs in the built documents.
 #keep_warnings = False
 
+# If true, Sphinx will warn about all references where the target cannot be
+# found.
+nitpicky = True
+
+# A list of (type, target) tuples (by default empty) that should be ignored when
+# generating warnings in “nitpicky mode”.
+nitpick_ignore = [
+    ('py:obj', 'bool'),
+    ('py:obj', 'dict'),
+    ('py:obj', 'int'),
+    ('py:obj', 'list'),
+    ('py:obj', 'str'),
+    ('py:obj', 'tuple'),
+]
+
 
 # -- Options for HTML output ----------------------------------------------
 

docs/getting_started.rst

@@ -10,9 +10,7 @@ Getting Started
         sys.path.append(ROOT_PATH)
     from fauxfactory import FauxFactory
 
-FauxFactory generates random data for your automated tests easily!
-
-Need a 10 characters string for one of your tests?
+Need a 10 character string for one of your tests?
 
 .. doctest::
 

docs/index.rst

@@ -8,4 +8,4 @@ FauxFactory generates random data for your automated tests easily!
 
     installation
     getting_started
-    methods_available
+    api

docs/installation.rst

@@ -3,12 +3,14 @@ Installation
 
 Python Package Index
 --------------------
-FauxFactory is available in PYPI and can be installed using pip::
+
+FauxFactory is available in PyPi and can be installed using pip::
 
     $ pip install fauxfactory
 
 From Source
 -----------
+
 You can install FauxFactory by downloading the latest version of the source
 code::
 

fauxfactory/__init__.py

@@ -22,57 +22,45 @@
 
 
 def codify(data):
-    """
-    Handles unicode compatibility with Python 3
+    """Convert ``data`` to a unicode string if running Python 2.
 
-    @type data: str
-    @param data: String to return using unicode.
+    :param str data: A string to be type cast.
+    :return: ``data``, but as unicode. ``data`` is never modified: if a type
+        cast is necessary, a copy of ``data`` is returned.
 
-    @rtype: str
-    @return: String in unicode format.
     """
-
-    try:
-        result = unicode(data)
-    except NameError:
-        result = data
-
-    return result
+    if sys.version_info[0] is 2:
+        return unicode(data)
+    return data
 
 
 class FauxFactory(object):
-    """
-    Generate random data for your tests.
-    """
+    """Generate random data for your tests."""
 
     @classmethod
     def _is_positive_int(cls, length):
-        """
-        Check that ``length`` argument is a valid integer, greater than zero.
+        """Check that ``length`` argument is an integer greater than zero.
 
-        @type length: int
-        @param length: The desired length of the string
+        :param int length: The desired length of the string
+        :raises: ``ValueError`` if ``length`` is not an ``int`` or is less than
+            1.
+        :returns: Nothing.
+        :rtype: None
 
-        @rtype: Exception
-        @return: A ``ValueError`` exception
         """
-
-        # Validate length argument
         if not isinstance(length, int) or length <= 0:
-            raise ValueError("%s is an invalid \'length\'." % length)
+            raise ValueError("{} is an invalid 'length'.".format(length))
 
     @classmethod
     def generate_string(cls, str_type, length):
-        """
-        Create of a wide variety of string types, of arbitrary length.
-
-        @type str_type: str
-        @param str_type: The desired type of string to be generated.
-        @type length: int
-        @param length: Length for generated strng.
+        """A simple wrapper that calls other string generation methods.
 
-        @rtype: int
-        @return: A random string of the type and length specified.
+        :param str str_type: The type of string which should be generated.
+        :param int length: The length of the generated string. Must be 1 or
+            greater.
+        :raises: ``Exception`` if an invalid ``str_type`` is specified.
+        :returns: A string.
+        :rtype: str
 
         Valid values for ``str_type`` are as follows:
 
@@ -83,27 +71,29 @@ def generate_string(cls, str_type, length):
         * latin1
         * numeric
         * utf8
-        """
 
-        # First lowercase the selected str type
-        str_type = str_type.lower()
-
-        if str_type == "alphanumeric":
-            return cls.generate_alphanumeric(length)
-        elif str_type == "alpha":
-            return cls.generate_alpha(length)
-        elif str_type == "latin1":
-            return cls.generate_latin1(length)
-        elif str_type == 'numeric':
-            return cls.generate_numeric_string(length)
-        elif str_type == "cjk":
-            return cls.generate_cjk(length)
-        elif str_type == "utf8":
-            return cls.generate_utf8(length)
-        elif str_type == "html":
-            return cls.generate_html(length)
+        """
+        str_types = (
+            'alpha',
+            'alphanumeric',
+            'cjk',
+            'html',
+            'latin1',
+            'numeric',
+            'utf8',
+        )
+        str_type_lower = str_type.lower()  # do not modify user data
+        if str_type_lower not in str_types:
+            raise Exception(  # FIXME: Raise a more specific exception.
+                '{} is not a supported string type. Valid string types are {}.'
+                ''.format(str_type_lower, str_types)
+            )
+        if str_type_lower == 'numeric':
+            method = cls.generate_numeric_string
         else:
-            raise Exception("%s is not a supported string type." % str_type)
+            method = getattr(cls, 'generate_{}'.format(str_type_lower))
+        return method(length)
+
 
     @classmethod
     def generate_alpha(cls, length=5):