[WIP] docstrings: automatically import pyunlocbox & numpy

doc/conf.py

@@ -20,6 +20,10 @@
 plot_html_show_source_link = False
 plot_html_show_formats = False
 plot_working_directory = '.'
+plot_pre_code = """
+import numpy as np
+from pyunlocbox import functions, solvers, acceleration, operators
+"""
 
 exclude_patterns = ['_build']
 source_suffix = '.rst'

pyunlocbox/acceleration.py

@@ -182,8 +182,6 @@ class backtracking(dummy):
 
     Examples
     --------
-    >>> import numpy as np
-    >>> from pyunlocbox import functions, solvers, acceleration
     >>> y = [4, 5, 6, 7]
     >>> x0 = np.zeros(len(y))
     >>> f1 = functions.norm_l1(y=y, lambda_=1.0)
@@ -284,8 +282,6 @@ class fista(dummy):
 
     Examples
     --------
-    >>> import numpy as np
-    >>> from pyunlocbox import functions, solvers, acceleration
     >>> y = [4, 5, 6, 7]
     >>> x0 = np.zeros(len(y))
     >>> f1 = functions.norm_l2(y=y)
@@ -367,8 +363,6 @@ class regularized_nonlinear(dummy):
 
     Examples
     --------
-    >>> import numpy as np
-    >>> from pyunlocbox import functions, solvers, acceleration
     >>> dim = 25;
     >>> np.random.seed(0)
     >>> xstar = np.random.rand(dim) # True solution
@@ -524,8 +518,6 @@ class fista_backtracking(backtracking, fista):
 
     Examples
     --------
-    >>> import numpy as np
-    >>> from pyunlocbox import functions, solvers, acceleration
     >>> y = [4, 5, 6, 7]
     >>> x0 = np.zeros(len(y))
     >>> f1 = functions.norm_l2(y=y)

pyunlocbox/functions.py

@@ -81,7 +81,6 @@ def _soft_threshold(z, T, handle_complex=True):
 
     Examples
     --------
-    >>> from pyunlocbox import functions
     >>> functions._soft_threshold([-2, -1, 0, 1, 2], 1)
     array([-1,  0,  0,  0,  1])
 
@@ -157,7 +156,6 @@ class func(object):
     Let's define a parabola as an example of the manual implementation of a
     function object :
 
-    >>> from pyunlocbox import functions
     >>> f = functions.func()
     >>> f._eval = lambda x: x**2
     >>> f._grad = lambda x: 2*x
@@ -356,7 +354,6 @@ class dummy(func):
 
     Examples
     --------
-    >>> from pyunlocbox import functions
     >>> f = functions.dummy()
     >>> x = [1, 2, 3, 4]
     >>> f.eval(x)
@@ -423,7 +420,6 @@ class norm_l1(norm):
 
     Examples
     --------
-    >>> from pyunlocbox import functions
     >>> f = functions.norm_l1()
     >>> f.eval([1, 2, 3, 4])
     10
@@ -473,7 +469,6 @@ class norm_l2(norm):
 
     Examples
     --------
-    >>> from pyunlocbox import functions
     >>> f = functions.norm_l2()
     >>> x = [1, 2, 3, 4]
     >>> f.eval(x)
@@ -537,7 +532,6 @@ class norm_nuclear(norm):
 
     Examples
     --------
-    >>> from pyunlocbox import functions
     >>> f = functions.norm_nuclear()
     >>> f.eval([[1, 2],[2, 3]])  # doctest:+ELLIPSIS
     4.47213595...
@@ -582,8 +576,6 @@ class norm_tv(norm):
 
     Examples
     --------
-    >>> import numpy as np
-    >>> from pyunlocbox import functions
     >>> f = functions.norm_tv()
     >>> x = np.arange(0, 16)
     >>> x = x.reshape(4, 4)
@@ -850,7 +842,6 @@ class proj_b2(proj):
 
     Examples
     --------
-    >>> from pyunlocbox import functions
     >>> f = functions.proj_b2(y=[1, 1])
     >>> x = [3, 3]
     >>> f.eval(x)

pyunlocbox/operators.py

@@ -35,8 +35,6 @@ def grad(x, dim=2, **kwargs):
 
     Examples
     --------
-    >>> import numpy as np
-    >>> from pyunlocbox import operators
     >>> x = np.arange(16).reshape(4, 4)
     >>> dx, dy = operators.grad(x)
 
@@ -82,8 +80,6 @@ def div(*args, **kwargs):
 
     Examples
     --------
-    >>> import numpy as np
-    >>> from pyunlocbox import operators
     >>> x = np.arange(16).reshape(4, 4)
     >>> dx, dy = operators.grad(x)
     >>> divx = operators.div(dx, dy)

pyunlocbox/solvers.py

@@ -129,8 +129,6 @@ def solve(functions, x0, solver=None, atol=None, dtol=None, rtol=1e-3,
 
     Examples
     --------
-    >>> import numpy as np
-    >>> from pyunlocbox import functions, solvers
 
     Define a problem:
 
@@ -446,8 +444,6 @@ class gradient_descent(solver):
 
     Examples
     --------
-    >>> import numpy as np
-    >>> from pyunlocbox import functions, solvers
     >>> dim = 25;
     >>> np.random.seed(0)
     >>> xstar = np.random.rand(dim) # True solution
@@ -521,8 +517,6 @@ class forward_backward(solver):
 
     Examples
     --------
-    >>> import numpy as np
-    >>> from pyunlocbox import functions, solvers
     >>> y = [4, 5, 6, 7]
     >>> x0 = np.zeros(len(y))
     >>> f1 = functions.norm_l2(y=y)
@@ -593,8 +587,6 @@ class generalized_forward_backward(solver):
 
     Examples
     --------
-    >>> import numpy as np
-    >>> from pyunlocbox import functions, solvers
     >>> y = [0.01, 0.2, 8, 0.3, 0 , 0.03, 7]
     >>> x0 = np.zeros(len(y))
     >>> f1 = functions.norm_l2(y=y)
@@ -681,8 +673,6 @@ class douglas_rachford(solver):
 
     Examples
     --------
-    >>> import numpy as np
-    >>> from pyunlocbox import functions, solvers
     >>> y = [4, 5, 6, 7]
     >>> x0 = np.zeros(len(y))
     >>> f1 = functions.norm_l2(y=y)
@@ -818,8 +808,6 @@ class mlfbf(primal_dual):
 
     Examples
     --------
-    >>> import numpy as np
-    >>> from pyunlocbox import functions, solvers
     >>> y = np.array([294, 390, 361])
     >>> L = np.array([[5, 9, 3], [7, 8, 5], [4, 4, 9], [0, 1, 7]])
     >>> x0 = np.zeros(len(y))
@@ -898,8 +886,6 @@ class projection_based(primal_dual):
 
     Examples
     --------
-    >>> import numpy as np
-    >>> from pyunlocbox import functions, solvers
     >>> y = np.array([294, 390, 361])
     >>> L = np.array([[5, 9, 3], [7, 8, 5], [4, 4, 9], [0, 1, 7]])
     >>> x0 = np.array([500, 1000, -400])

pyunlocbox/tests/test_docstrings.py

@@ -17,15 +17,28 @@ def gen_recursive_file(root, ext):
                 yield os.path.join(root, name)
 
 
-def test_docstrings(root, ext):
+def test_docstrings(root, ext, setup=None):
     files = list(gen_recursive_file(root, ext))
-    return doctest.DocFileSuite(*files, module_relative=False)
+    return doctest.DocFileSuite(*files, setUp=setup, module_relative=False)
+
+
+def setup(doctest):
+    import numpy
+    import pyunlocbox
+    doctest.globs = {
+        'functions': pyunlocbox.functions,
+        'solvers': pyunlocbox.solvers,
+        'acceleration': pyunlocbox.acceleration,
+        'operators': pyunlocbox.operators,
+        'np': numpy,
+    }
 
 
 # Docstrings from reference documentation.
-suite_reference = test_docstrings('pyunlocbox', '.py')
+suite_reference = test_docstrings('pyunlocbox', '.py', setup)
 
 # Docstrings from tutorials.
+# No setup to not forget imports.
 suite_tutorials = test_docstrings('.', '.rst')
 
 suite = unittest.TestSuite([suite_reference, suite_tutorials])