Merge pull request #423 from kain88-de/docs

Proof that numpy-style docs can be used with normal ReST

package/MDAnalysis/lib/mdamath.py

@@ -36,18 +36,27 @@
 
 from ..exceptions import NoDataError
 
+
 # geometric functions
 def norm(v):
-    r"""Returns the length of a vector, ``sqrt(v.v)``.
+    r"""Calculate the norm of a vector v.
 
-    .. math::
+    .. math:: v = \sqrt{\mathbf{v}\cdot\mathbf{v}}
 
-       v = \sqrt{\mathbf{v}\cdot\mathbf{v}}
+    This version is faster then numpy.linalg.norm because it only works for a
+    single vector and therefore can skip a lot of the additional fuss
+    linalg.norm does.
 
-    Faster than :func:`numpy.linalg.norm` because no frills.
+    Parameters
+    ----------
+    v: array_like
+        1D array of shape (N) for a vector of length N
+
+    Returns
+    -------
+    float
+        norm of the vector
 
-    .. versionchanged:: 0.11.0
-       Moved into lib.mdamath
     """
     return np.sqrt(np.dot(v, v))
 

package/doc/sphinx/source/conf.py

@@ -46,16 +46,8 @@ def __getattr__(cls, name):
 # documentation root, use os.path.abspath to make it absolute, like shown
 # here.
 
-# Little trick to make sure sphinx use the dev build if present
-build_path = "../../../build/lib.%s-%s-%s" % (platform.system().lower(),
-                                              platform.machine(),
-                                              ".".join(platform.python_version_tuple()[:2]))
-build_path = os.path.abspath(build_path)
-if os.path.exists(build_path):
-    sys.path.insert(0, build_path)
-
-#sys.path.insert(0, os.path.abspath('.'))
-#sys.path.insert(0, '../../../MDAnalysis/analysis/')
+# make sure sphinx always uses the current branch
+sys.path.insert(0, os.path.abspath('../../..'))
 
 # -- General configuration -----------------------------------------------------
 
@@ -65,7 +57,8 @@ def __getattr__(cls, name):
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx',
-              'sphinx.ext.mathjax', 'sphinx.ext.viewcode']
+              'sphinx.ext.mathjax', 'sphinx.ext.viewcode',
+              'sphinx.ext.napoleon',]
 mathjax_path = 'https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML'
 
 # Add any paths that contain templates here, relative to this directory.