Move documentation outside of source tree. Remove `doc` import from __init__.

1 files changed, 125 insertions, 0 deletions

diff --git a/doc/example.py b/doc/example.py
new file mode 100644
index 000000000..152e2a622
--- /dev/null
+++ b/doc/example.py
@@ -0,0 +1,125 @@
+"""This is the docstring for the example.py module.  Modules names should
+have short, all-lowercase names.  The module name may have underscores if
+this improves readability.
+
+Every module should have a docstring at the very top of the file.  The
+module's docstring may extend over multiple lines.  If your docstring does
+extend over multiple lines, the closing three quotation marks must be on
+a line by itself, preferably preceeded by a blank line.
+
+"""
+import os # standard library imports first
+
+# Do NOT import using *, e.g. from numpy import *
+#
+# Import the module using
+#
+#   import numpy
+#
+# instead or import individual functions as needed, e.g
+#
+#  from numpy import array, zeros
+#
+# If you prefer the use of abbreviated module names, we suggest the
+# convention used by NumPy itself::
+
+import numpy as np
+import scipy as sp
+import matplotlib as mpl
+import matplotlib.pyplot as plt
+
+# These abbreviated names are not to be used in docstrings; users must
+# be able to paste and execute docstrings after importing only the
+# numpy module itself, unabbreviated.
+
+from my_module import my_func, other_func
+
+def foo(var1, var2, long_var_name='hi') :
+    """A one-line summary that does not use variable names or the
+    function name.
+
+    Several sentences providing an extended description. Refer to
+    variables using back-ticks, e.g. `var`.
+
+    Parameters
+    ----------
+    var1 : array_like
+        Array_like means all those objects -- lists, nested lists, etc. --
+        that can be converted to an array.  We can also refer to
+        variables like `var1`.
+    var2 : int
+        The type above can either refer to an actual Python type
+        (e.g. ``int``), or describe the type of the variable in more
+        detail, e.g. ``(N,) ndarray`` or ``array_like``.
+    Long_variable_name : {'hi', 'ho'}, optional
+        Choices in brackets, default first when optional.
+
+    Returns
+    -------
+    describe : type
+        Explanation
+    output
+        Explanation
+    tuple
+        Explanation
+    items
+        even more explaining
+
+    Other Parameters
+    ----------------
+    only_seldom_used_keywords : type
+        Explanation
+    common_parameters_listed_above : type
+        Explanation
+
+    Raises
+    ------
+    BadException
+        Because you shouldn't have done that.
+
+    See Also
+    --------
+    otherfunc : relationship (optional)
+    newfunc : Relationship (optional), which could be fairly long, in which
+              case the line wraps here.
+    thirdfunc, fourthfunc, fifthfunc
+
+    Notes
+    -----
+    Notes about the implementation algorithm (if needed).
+
+    This can have multiple paragraphs.
+
+    You may include some math:
+
+    .. math:: X(e^{j\omega } ) = x(n)e^{ - j\omega n}
+
+    And even use a greek symbol like :math:`omega` inline.
+
+    References
+    ----------
+    Cite the relevant literature, e.g. [1]_.  You may also cite these
+    references in the notes section above.
+
+    .. [1] O. McNoleg, "The integration of GIS, remote sensing,
+       expert systems and adaptive co-kriging for environmental habitat
+       modelling of the Highland Haggis using object-oriented, fuzzy-logic
+       and neural-network techniques," Computers & Geosciences, vol. 22,
+       pp. 585-588, 1996.
+
+    Examples
+    --------
+    These are written in doctest format, and should illustrate how to
+    use the function.
+
+    >>> a=[1,2,3]
+    >>> print [x + 3 for x in a]
+    [4, 5, 6]
+    >>> print "a\n\nb"
+    a
+    <BLANKLINE>
+    b
+
+    """
+
+    pass