BLD: use travis-sphinx to build and deploy documentation

Also fix some doc issues along the way

.travis.yml

@@ -7,7 +7,13 @@ python:
 # See http://conda.pydata.org/docs/travis.html
 install:
   - sudo apt-get update
-  # We do this conditionally because it saves us some downloading if the version is the same.
+
+  # Install LaTeX to render the math formulas in the docs
+  - if [[ "$TRAVIS_PYTHON_VERSION" == "3.5" && "$TRAVIS_BRANCH" == "master" ]]; then
+      sudo apt-get install texlive-latex-base texlive-latex-recommended texlive-latex-extra dvipng;
+    fi
+
+  # Install miniconda according to Python version of the build (saves downloading if versions match)
   - if [[ "$TRAVIS_PYTHON_VERSION" == "2.7" ]]; then
       wget https://repo.continuum.io/miniconda/Miniconda-latest-Linux-x86_64.sh -O miniconda.sh;
     else
@@ -21,30 +27,32 @@ install:
   # Useful for debugging any issues with conda
   - conda info -a
 
-  # Install dependencies and our package
-  - conda create -q -n test-environment python=$TRAVIS_PYTHON_VERSION numpy scipy nomkl
+  # Install dependencies and enter test environment
+  - conda create -q -n test-environment python=$TRAVIS_PYTHON_VERSION numpy scipy future nomkl sphinx sphinx_rtd_theme
   - source activate test-environment
-  - pip install -e .
 
   # Sphinx doc integration
-  - pip install --user travis-sphinx
+  - pip install travis-sphinx
+
+  # Install our package
+  - pip install -e .
+
 
 before_script:
   - pip install -r test_requirements.txt
 
 script:
-  # Run tests, producing a coverage report and
+  # Run tests, including PEP8 check, and produce a coverage report
   - py.test --doctest-modules --cov --cov-report term-missing --pep8
   # Build the Sphinx doc
-  - travis-sphinx build
+  - cd $TRAVIS_BUILD_DIR/doc/source && python generate_doc.py && cd -
+  - travis-sphinx -n -s $TRAVIS_BUILD_DIR/doc/source build
 
 after_success:
   # Push coverage report to coveralls
   - coveralls
-  # Deploy the Sphinx doc to gh-pages if the push was to the master branch (and not a PR)
-  #- if [ "$TRAVIS_BRANCH" = "master" -a "$TRAVIS_PULL_REQUEST" = "false" ]; then
-  #      travis-sphinx deploy
-  #  fi
-
-  # FOR TESTING, REMOVE WHEN DONE
-  - travis-sphinx deploy
+  # Deploy the Sphinx doc to gh-pages (only for master branch and one Python version)
+  # See https://github.com/Syntaf/travis-sphinx
+  - if [[ "$TRAVIS_PYTHON_VERSION" == "3.5" && "$TRAVIS_BRANCH" == "master" ]]; then
+      travis-sphinx deploy;
+    fi

doc/source/conf.py

@@ -105,14 +105,14 @@ def __getattr__(cls, name):
 
 if not on_rtd:
     # TODO: fix this once RTD updates their intersphinx version
-    extensions += ['sphinx.ext.intersphinx']
+    extensions.append('sphinx.ext.intersphinx')
 
     # Intersphinx to get numpy targets
     intersphinx_mapping = {
-        'python': ('http://python.readthedocs.org/en/latest/', None),
-        'numpy': ('http://numpy.readthedocs.org/en/latest/', None),
+        'python': ('http://python.readthedocs.io/en/latest/', None),
+        'numpy': ('http://numpy.readthedocs.io/en/latest/', None),
         'scipy': ('http://docs.scipy.org/doc/scipy/reference/', None),
-        'matplotlib': ('http://matplotlib.sourceforge.net/', None)}
+        'matplotlib': ('http://matplotlib.org/objects.inv', None)}
 
 # Stop autodoc from skipping __init__
 
@@ -172,9 +172,9 @@ def setup(app):
 # built documents.
 #
 # The short X.Y version.
-version = 'beta'
+version = '0.4'
 # The full version, including alpha/beta/rc tags.
-release = 'beta'
+release = '0.4.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

doc/source/guide/introduction/solvers.rst

@@ -0,0 +1,5 @@
+.. _math_solvers:
+
+######################################################
+Solution methods for optimization problems ("solvers")
+######################################################

doc/source/math/solvers/advanced/proximal_operators.rst

@@ -58,7 +58,7 @@ The convex conjugate of :math:`f` is defined as
 .. math:: f^*(y) = \sup_{x\in X} \langle y,x\rangle - f(x)
 
 where :math:`\langle\cdot,\cdot\rangle` denotes inner product. For more
-on convex conjugate and convex analysis see [R1970]_
+on convex conjugate and convex analysis see [Roc1970]_
 or `Wikipedia <https://en.wikipedia.org/wiki/Convex_conjugate>`_.
 
 For more details on proximal operators including how to evaluate the

doc/source/math/trafos/fourier_transform.rst

@@ -17,7 +17,7 @@ The `Fourier Transform`_ (FT) of a function :math:`f` belonging to the `Lebesgue
 .. math::
     \widehat{f}(\xi) = \mathcal{F}(f)(\xi) = (2\pi)^{-\frac{1}{2}}
     \int_{\mathbb{R}} f(x)\ e^{-i x \xi} \, \mathrm{d}x.
-    :label: def_fourier     
+    :label: def_fourier
 
 (Note that this definition differs from the one in the linked article by the placement of the
 factor :math:`2\pi`.) By unique continuation, the bounded FT operator can be
@@ -40,7 +40,7 @@ The inverse of :math:`\mathcal{F}` on its range is given by the formula
     :label: def_fourier_inverse
 
 For :math:`p = 2`, the conjugate exponent is :math:`q = 2`, and the FT is a unitary
-operator on :math:`L`2(\mathbb{R})` according to `Parseval's Identity`_
+operator on :math:`L^2(\mathbb{R})` according to `Parseval's Identity`_
 
 .. math::
     \int_{\mathbb{R}} \lvert f(x)\rvert^2\, \mathrm{d}x =
@@ -62,9 +62,9 @@ Further Properties
     \mathcal{F}\big(f(a \cdot)\big)(\xi) = a^{-1} \widehat{f}(a^{-1}\xi),
 
     \frac{\mathrm{d}}{\mathrm{d} \xi} \widehat{f}(\xi) = \mathcal{F}(-i x f)(\xi)
-    
+
     \mathcal{F}(f')(\xi) = i \xi \widehat{f}(\xi).
-    
+
 The first identity implies in particular that for real-valued :math:`f`, it is
 :math:`\overline{\mathcal{F}(\phi)}(\xi) = \mathcal{F}(\phi)(-\xi)`, i.e. the FT is
 completely known already from the its values in a half-space only. This property is later exploited
@@ -98,7 +98,7 @@ Discretization of the Fourier transform operator means evaluating the Fourier in
     :label: discr_function
 
 with coefficients :math:`\bar f = (f_0, \dots, f_{n-1}) \in \mathbb{C}^n` and functions
-:math:`\phi_0, \dots, \phi_{n-1}`. This approach follows from the way , but can be 
+:math:`\phi_0, \dots, \phi_{n-1}`. This approach follows from the way , but can be
 We consider in particular functions generated from a single
 kernel :math:`\phi` via
 
@@ -222,8 +222,8 @@ The inverse of the discretized formula :eq:`discr_fourier_final` is instead gain
 the identity
 
 .. math::
-    \sum_{j=0}^{N-1} e^{i 2\pi \frac{(l-k)j}{N}} 
-    &= \sum_{j=0}^{N-1} \Big( e^{i 2\pi \frac{(l-k)}{N}} \Big)^j = 
+    \sum_{j=0}^{N-1} e^{i 2\pi \frac{(l-k)j}{N}}
+    &= \sum_{j=0}^{N-1} \Big( e^{i 2\pi \frac{(l-k)}{N}} \Big)^j =
     \begin{cases}
       N, & \text{if } l = k, \\
       \frac{1 - e^{i 2\pi (l-k)}}{1 - e^{i 2\pi (l-k)/N}} = 0, & \text{else}
@@ -262,7 +262,7 @@ Adjoint operator
 ----------------
 
 If the FT is defined between the complex Hilbert spaces :math:`L^2(\mathbb{R}, \mathbb{C})`,
-one can easily show that the operator is unitary, and therefore its adjoint is equal to its
+one can easily show that the operator is unitary, and therefore its adjoint is equal to the
 inverse.
 
 However, if the domain is a real space, :math:`L^2(\mathbb{R}, \mathbb{C})`, one cannot even
@@ -278,8 +278,8 @@ the real and imaginary parts in the range with components of a product space ele
 .. math::
     \widetilde{\mathcal{F}}: L^2(\mathbb{R}, \mathbb{R}) \longrightarrow
     \big[L^2(\mathbb{R}, \mathbb{R})\big]^2,
-    
-    \widetilde{\mathcal{F}} = \big(\Re \big(\mathcal{F}(f)\big), \Im \big(\mathcal{F}(f)\big)\big) =
+
+    \widetilde{\mathcal{F}}(f) = \big(\Re \big(\mathcal{F}(f)\big), \Im \big(\mathcal{F}(f)\big)\big) =
     \big( \mathcal{F}_{\mathrm{c}}(f), -\mathcal{F}_{\mathrm{s}}(f) \big),
 
 where :math:`\mathcal{F}_{\mathrm{c}}` and :math:`\mathcal{F}_{\mathrm{s}}` are the
@@ -289,7 +289,7 @@ Hilbert spaces, and thus the adjoint of the above defined transform is given by
 .. math::
     \widetilde{\mathcal{F}}^*: \big[L^2(\mathbb{R}, \mathbb{R})\big]^2 \longrightarrow
     L^2(\mathbb{R}, \mathbb{R})
-    
+
     \widetilde{\mathcal{F}}^*(g_1, g_2) = \mathcal{F}_{\mathrm{c}}(g_1) -
     \mathcal{F}_{\mathrm{s}}(g_2).
 

doc/source/release_notes.rst

@@ -306,5 +306,3 @@ First official release.
 .. _Fourier Transform: https://en.wikipedia.org/wiki/Fourier_transform
 .. _Numpy's FFTPACK based transform: http://docs.scipy.org/doc/numpy/reference/routines.fft.html
 .. _pyFFTW: https://pypi.python.org/pypi/pyFFTW
-
-.. include:: prs.inc

odl/discr/tensor_ops.py

@@ -471,7 +471,7 @@ class PointwiseInner(PointwiseInnerBase):
 
     This operator takes the (weighted) inner product
 
-        ``<F(x), G(x)> = sum_j ( w_j * F_j(x) * conj(G_j(x)) )
+        ``<F(x), G(x)> = sum_j ( w_j * F_j(x) * conj(G_j(x)) )``
 
     for a given vector field ``G``, where ``F`` is the vector field
     acting as a variable to this operator.

odl/phantom/__init__.py

@@ -15,7 +15,7 @@
 # You should have received a copy of the GNU General Public License
 # along with ODL.  If not, see <http://www.gnu.org/licenses/>.
 
-"""Test data for tomography problems."""
+"""Test objects for tomography problems."""
 
 from __future__ import absolute_import
 

odl/phantom/transmission.py

@@ -83,7 +83,7 @@ def shepp_logan(space, modified=False):
 
     References
     ----------
-    .. Shepp-Logan phantom: en.wikipedia.org/wiki/Shepp–Logan_phantom
+    .. _Shepp-Logan phantom: en.wikipedia.org/wiki/Shepp–Logan_phantom
     """
     if space.ndim == 2:
         ellipses = _shepp_logan_ellipse_2d()

odl/solvers/advanced/douglas_rachford.py

@@ -51,29 +51,29 @@ def douglas_rachford_pd(x, prox_f, prox_cc_g, L, tau, sigma, niter,
     ----------
     x : `LinearSpaceVector`
         Initial point, updated in-place.
-    prox_f : `callable`
+    prox_f : callable
         `proximal factory` for the function ``f``.
-    prox_cc_g : `sequence` of `callable`'s
+    prox_cc_g : sequence of callable
         Sequence of `proximal factory` for the convex conjuates of the
         functions ``g_i``.
-    L : `sequence` of `Operator`'s
-        Sequence of `Opeartor`s` with as many elements as ``prox_cc_gs``.
+    L : sequence of `Operator`'s
+        Sequence of operators with as many elements as ``prox_cc_gs``.
     tau : `float`
         Step size parameter for ``prox_f``.
-    sigma : `sequence` of  `float`
+    sigma : sequence of float
         Step size parameters for the ``prox_cc_g``s.
-    niter : `int`
+    niter : int
         Number of iterations.
-    callback : `callable`, optional
+    callback : callable, optional
         Function called with the current iterate after each iteration.
 
     Other Parameters
     ----------------
-    prox_cc_l : `sequence` of `callable`'s, optional
+    prox_cc_l : sequence of callable, optional
         Sequence of `proximal factory` for the convex conjuates of the
         functions ``l_i``.
         If omitted, the simpler problem without ``l_i``  will be considered.
-    lam : `float` or `callable`, optional
+    lam : float or callable, optional
         Overrelaxation step size. If callable, should take an index (zero
         indexed) and return the corresponding step size.
 

odl/solvers/advanced/proximal_operators.py

@@ -421,11 +421,11 @@ def proximal_box_constraint(space, lower=None, upper=None):
     with x being an element in ``space``.
 
     For a step size ``tau``, the proximal operator of ``tau * G^*`` is the
-    point-wise non-negativity thresholding of x
+    point-wise non-negativity thresholding of ``x``::
 
-                              a if x < a,
+                            { a if x < a,
          prox[tau * G](x) = { x if a <= x <= b
-                              b if x > b
+                            { b if x > b
 
     It is independent of tau and invariant under a positive rescaling of G
     which leaves the indicator function as it stands.
@@ -584,13 +584,13 @@ def proximal_l2(space, lam=1, g=None):
     Function for the proximal operator of the functional ``F`` where ``F``
     is the l2-norm (or distance to g, if given)
 
-        F(x) =  lam ||x - g||_2
+        ``F(x) =  lam ||x - g||_2``
 
-    For a step size ``sigma``, the proximal operator of ``sigma * F``is given
-    by
+    For a step size ``sigma``, the proximal operator of ``sigma * F``
+    is given by::
 
         prox[sigma * F](y) = { (1.0 - c / ||x-g||) * x  + c * g    if c < 1
-                               g                                   else
+                             { g                                   else
 
     where ``c = sigma * lam / ||x - g||_2``.
 
@@ -600,13 +600,13 @@ def proximal_l2(space, lam=1, g=None):
         Domain of F(x). Needs to be a Hilbert space.
         That is, have an inner product (`LinearSpace.inner`).
     g : ``space`` element
-        An element in ``space``
-    lam : positive `float`
-        Scaling factor or regularization parameter
+        An element in ``space``.
+    lam : positive float
+        Scaling factor or regularization parameter.
 
     Returns
     -------
-    prox_factory : `callable`
+    prox_factory : callable
         Factory for the proximal operator to be initialized
 
     Notes
@@ -619,7 +619,6 @@ def proximal_l2(space, lam=1, g=None):
     proximal_l2_squared : proximal for squared norm/distance
     proximal_cconj_l2 : proximal for convex conjugate
     """
-
     lam = float(lam)
 
     if g is not None and g not in space:
@@ -789,42 +788,43 @@ def proximal_cconj_l1(space, lam=1, g=None, isotropic=False):
     """Proximal operator factory of the convex conj of the l1-norm/distance.
 
     Function for the proximal operator of the convex conjugate of the
-    functional F where F is an l1-norm (or distance to g, if given)
+    functional ``F`` where ``F`` is an l1-norm (or distance to g, if given)
 
-        F(x) = lam ||x - g||_1
+        ``F(x) = lam ||x - g||_1``
 
     with x and g elements in ``space`` and scaling factor lam.
 
-    The convex conjugate F^* of F is given by the indicator function of
-    the set box(lam)
+    The convex conjugate of ``F`` is given by the indicator function
+    of the set box(lam),
 
-        F^*(y) = lam ind_{box(lam)}(|y / lam| + <y / lam, g>)
+        ``F^*(y) = lam ind_{box(lam)}(|y / lam| + <y / lam, g>)``,
 
-    where box(lam) is a hypercube centered at the origin with width 2 lam.
+    where ``box(lam)`` is a hypercube centered at the origin with width
+    ``2 * lam``.
 
     For a step size ``sigma``, the proximal operator of ``sigma * F^*`` is
     given by
 
-        prox[sigma * F^*](y) = lam (y - sigma g) / (max(lam, |y - sigma g|)
+        ``prox[sigma * F^*](y) = lam (y - sigma g) /
+        (max(lam, |y - sigma g|)``
 
-    An alternative formulation is available for `ProductSpace`'s, in that case
-    the ``isotropic`` parameter can be used, giving
+    An alternative formulation is available for `ProductSpace`'s, in which
+    case the ``isotropic`` parameter can be used, giving
 
-        F(x) = lam || ||x - g||_2 ||_1
+        ``F(x) = lam || ||x - g||_2 ||_1``.
 
     In this case, the dual is
 
-        F^*(y) = lam ind_{box(lam)}(||y / lam||_2 + <y / lam, g>)
+        ``F^*(y) = lam ind_{box(lam)}(||y / lam||_2 + <y / lam, g>)``.
 
     For a step size ``sigma``, the proximal operator of ``sigma * F^*`` is
     given by
 
-        prox[sigma * F^*](y) =
-            lam (y - sigma g) / (max(lam, ||y - sigma g||_2)
+        ``prox[sigma * F^*](y) =
+        lam (y - sigma g) / (max(lam, ||y - sigma g||_2)``
 
-    where max(.,.) thresholds the lower bound of ||y||_2 point-wise and
-    1 is a vector in the space of ||y||_2 with all components set
-    to 1.
+    where ``max(.,.)`` thresholds the lower bound of ``||y||_2``
+    point-wise.
 
     Parameters
     ----------

odl/tomo/geometry/spect.py

@@ -39,13 +39,14 @@ class ParallelHoleCollimatorGeometry(Parallel3dAxisGeometry):
     def __init__(self, apart, dpart, det_rad, axis=[0, 0, 1],
                  **kwargs):
         """Initialize a new instance.
+
         Parameters
         ----------
         apart : 1-dim. `RectPartition`
             Partition of the angle interval
         dpart : 2-dim. `RectPartition`
             Partition of the detector parameter rectangle
-        det_rad : positive `float`
+        det_rad : positive float
             Radius of the circular detector orbit.
         axis : `array-like`, shape ``(3,)``, optional
             Fixed rotation axis.