WIP travis sphinx commit (pymc-devs#2698)

* Clean travis sphinx commit

* Add pandoc, sort requirements-dev.txt

* More tidying, add pandoc again

* Only build docs in one process

* Fix logic, only deploy docs on master build

* travis-sphinx is smart enough to default to master branch

* Write CNAME on travis deploy

* put flag earlier

* Install travis-sphinx 2.0.0 from github

* Default docs folder moved, make it explicit

.travis.yml

@@ -7,14 +7,20 @@ cache:
     - $HOME/minicoda2
     - $HOME/minicoda3
 
+addons:
+  apt_packages:
+    - pandoc
+
 before_install:
   - . ./scripts/install_miniconda.sh
   - sh -e /etc/init.d/xvfb start
   - export DISPLAY=":99.0"
 
 install:
   - . ./scripts/create_testenv.sh
-  - pip install coveralls pylint
+  - pip install coveralls pylint 
+  - pip install git+git://github.com/Syntaf/travis-sphinx@7cdd18f20#egg=travis-sphinx
+  - pip install -r requirements-dev.txt
 
 env:
   - PYTHON_VERSION=2.7 FLOATX='float32' TESTCMD="--durations=10 --ignore=pymc3/tests/test_examples.py --cov-append --ignore=pymc3/tests/test_distributions_random.py --ignore=pymc3/tests/test_variational_inference.py --ignore=pymc3/tests/test_shared.py --ignore=pymc3/tests/test_smc.py --ignore=pymc3/tests/test_updates.py --ignore=pymc3/tests/test_posteriors.py --ignore=pymc3/tests/test_sampling.py"
@@ -26,8 +32,9 @@ env:
   - PYTHON_VERSION=2.7 FLOATX='float64' TESTCMD="--durations=10 --cov-append pymc3/tests/test_examples.py pymc3/tests/test_posteriors.py"
   - PYTHON_VERSION=3.6 FLOATX='float64' TESTCMD="--durations=10 --cov-append --ignore=pymc3/tests/test_examples.py --ignore=pymc3/tests/test_distributions_random.py --ignore=pymc3/tests/test_variational_inference.py --ignore=pymc3/tests/test_shared.py --ignore=pymc3/tests/test_smc.py --ignore=pymc3/tests/test_updates.py --ignore=pymc3/tests/test_posteriors.py --ignore=pymc3/tests/test_sampling.py"
   - PYTHON_VERSION=3.6 FLOATX='float64' TESTCMD="--durations=10 --cov-append pymc3/tests/test_distributions_random.py pymc3/tests/test_shared.py pymc3/tests/test_smc.py pymc3/tests/test_sampling.py"
-  - PYTHON_VERSION=3.6 FLOATX='float64' TESTCMD="--durations=10 --cov-append pymc3/tests/test_examples.py pymc3/tests/test_posteriors.py"
+  - PYTHON_VERSION=3.6 FLOATX='float64' BUILD_DOCS="true" TESTCMD="--durations=10 --cov-append pymc3/tests/test_examples.py pymc3/tests/test_posteriors.py"
   - PYTHON_VERSION=3.6 FLOATX='float64' TESTCMD="--durations=10 --cov-append pymc3/tests/test_variational_inference.py pymc3/tests/test_updates.py"
+
 script:
   - . ./scripts/test.sh $TESTCMD
   - . ./scripts/confirm_mpl_optional.sh

docs/source/api/gp.rst

@@ -8,13 +8,16 @@ GP Implementations
 Mean Functions
 --------------
 
-.. currentmodule:: pymc3.gp.cov
+.. currentmodule:: pymc3.gp.mean
 .. autosummary::
 
    Zero
    Constant
    Linear
 
+.. automodule:: pymc3.gp.mean
+   :members:
+
 Covariance Functions
 --------------------
 

docs/source/api/math.rst

@@ -1,11 +1,10 @@
-****
+====
 Math
-****
+====
 
-This submodule contains various mathematical functions. Most of them
-are imported directly from theano.tensor (see there for more
-details). Doing any kind of math with PyMC3 random variables, or
-defining custom likelihoods or priors requires you to use these theano
+This submodule contains various mathematical functions. Most of them are imported directly 
+from theano.tensor (see there for more details). Doing any kind of math with PyMC3 random 
+variables, or defining custom likelihoods or priors requires you to use these theano
 expressions rather than NumPy or Python code.
 
 .. currentmodule:: pymc3.math

docs/source/conf.py

@@ -38,6 +38,7 @@
     'sphinx.ext.doctest',
     'sphinx.ext.mathjax',
     'sphinx.ext.napoleon',
+    'numpydoc',
     'nbsphinx',
     'IPython.sphinxext.ipython_console_highlighting',
 ]

docs/source/examples.rst

@@ -26,7 +26,7 @@ Applied
    notebooks/BEST.ipynb
    notebooks/multilevel_modeling.ipynb
    notebooks/stochastic_volatility.ipynb
-   notebooks/probabilistic-matrix-factorization.ipynb
+   notebooks/probabilistic_matrix_factorization.ipynb
    notebooks/rugby_analytics.ipynb
    notebooks/survival_analysis.ipynb
    notebooks/dawid-skene.ipynb
@@ -72,11 +72,9 @@ Variational Inference
 =====================
 
 .. toctree::
-   notebooks/GLM-hierarchical-ADVI.ipynb
    notebooks/GLM-hierarchical-advi-minibatch.ipynb
    notebooks/lda-advi-aevb.ipynb
    notebooks/bayesian_neural_network_advi.ipynb
    notebooks/convolutional_vae_keras_advi.ipynb
-   notebooks/bayesian_neural_network_opvi-advi.ipynb
-   notebooks/empirical-approx-overvirew.ipynb
+   notebooks/empirical-approx-overview.ipynb
    notebooks/normalizing_flows_overview.ipynb

pymc3/distributions/bound.py

@@ -174,8 +174,8 @@ class Bound(object):
     upper : float or array like, optional
         Upper bound of the distribution.
 
-    Example
-    -------
+    Examples
+    --------
     with pm.Model():
         NegativeNormal = pm.Bound(pm.Normal, upper=0.0)
         par1 = NegativeNormal('par2', mu=0.0, sd=1.0, testval=1.0)

pymc3/distributions/multivariate.py

@@ -652,8 +652,8 @@ class Wishart(Continuous):
     V : array
         p x p positive definite matrix.
 
-    Note
-    ----
+    Notes
+    -----
     This distribution is unusable in a PyMC3 model. You should instead
     use LKJCholeskyCov or LKJCorr.
     """
@@ -746,8 +746,8 @@ def WishartBartlett(name, S, nu, is_cholesky=False, return_cholesky=False, testv
     testval : ndarray
         p x p positive definite matrix used to initialize
 
-    Note
-    ----
+    Notes
+    -----
     This is not a standard Distribution class but follows a similar
     interface. Besides the Wishart distribution, it will add RVs
     c and z to your model which make up the matrix.
@@ -866,9 +866,7 @@ class LKJCholeskyCov(Continuous):
             # Extract the standard deviations
             stds = tt.sqrt(tt.diag(cov))
 
-    Implementation
-    --------------
-    In the unconstrained space all values of the cholesky factor
+    **Implementation** In the unconstrained space all values of the cholesky factor
     are stored untransformed, except for the diagonal entries, where
     we use a log-transform to restrict them to positive values.
 

pymc3/gp/gp.py

@@ -72,7 +72,7 @@ class Latent(Base):
     mean_func : None, instance of Mean
         The mean function.  Defaults to zero.
 
-    Example
+    Examples
     --------
     .. code:: python
 
@@ -342,7 +342,7 @@ class Marginal(Base):
     mean_func : None, instance of Mean
         The mean function.  Defaults to zero.
 
-    Example
+    Examples
     --------
     .. code:: python
 
@@ -581,7 +581,7 @@ class MarginalSparse(Marginal):
     approx : string
         The approximation to use.  Must be one of `VFE`, `FITC` or `DTC`.
 
-    Example
+    Examples
     --------
     .. code:: python
 

pymc3/math.py

@@ -38,8 +38,8 @@ def logsumexp(x, axis=None):
 
 def logaddexp(a, b):
     diff = b - a
-    return tt.switch(diff > 0, 
-                    b + tt.log1p(tt.exp(-diff)), 
+    return tt.switch(diff > 0,
+                    b + tt.log1p(tt.exp(-diff)),
                     a + tt.log1p(tt.exp(diff)))
 
 def invlogit(x, eps=sys.float_info.epsilon):
@@ -55,12 +55,12 @@ def flatten_list(tensors):
 
 
 class LogDet(Op):
-    """Compute the logarithm of the absolute determinant of a square
+    r"""Compute the logarithm of the absolute determinant of a square
     matrix M, log(abs(det(M))) on the CPU. Avoids det(M) overflow/
     underflow.
 
-    Note
-    ----
+    Notes
+    -----
     Once PR #3959 (https://github.com/Theano/Theano/pull/3959/) by harpone is merged,
     this must be removed.
     """
@@ -104,7 +104,7 @@ def expand_packed_triangular(n, packed, lower=True, diagonal_only=False):
 
     Triangular matrices can be stored with better space efficiancy by
     storing the non-zero values in a one-dimensional array. We number
-    the elements by row like this (for lower or upper triangular matrices)::
+    the elements by row like this (for lower or upper triangular matrices):
 
         [[0 - - -]     [[0 1 2 3]
          [1 2 - -]      [- 4 5 6]
@@ -236,7 +236,7 @@ def infer_shape(self, nodes, shapes):
 
 
 def block_diagonal(matrices, sparse=False, format='csr'):
-    """See scipy.sparse.block_diag or
+    r"""See scipy.sparse.block_diag or
     scipy.linalg.block_diag for reference
 
     Parameters

pymc3/sampling.py

@@ -317,7 +317,7 @@ def sample(draws=500, step=None, init='auto', n_init=200000, start=None,
         random_seed = [np.random.randint(2 ** 30) for _ in range(chains)]
     if not isinstance(random_seed, Iterable):
         raise TypeError('Invalid value for `random_seed`. Must be tuple, list or int')
-        
+
     if 'chain' in kwargs:
         chain_idx = kwargs['chain']
         warnings.warn("The chain argument has been deprecated. Use chain_idx instead.",
@@ -508,8 +508,8 @@ def iter_sample(draws, step, start=None, trace=None, chain=0, tune=None,
     random_seed : int or list of ints
         A list is accepted if more if `njobs` is greater than one.
 
-    Example
-    -------
+    Examples
+    --------
     ::
 
         for trace in iter_sample(500, step):

pymc3/stats.py

@@ -371,9 +371,9 @@ def compare(traces, models, ic='WAIC', method='stacking', b_samples=1000,
         are:
             - 'stacking' : (default) stacking of predictive distributions.
             - 'BB-pseudo-BMA' : pseudo-Bayesian Model averaging using Akaike-type
-        weighting. The weights are stabilized using the Bayesian bootstrap
+               weighting. The weights are stabilized using the Bayesian bootstrap
             - 'pseudo-BMA': pseudo-Bayesian Model averaging using Akaike-type
-        weighting, without Bootstrap stabilization (not recommended)
+               weighting, without Bootstrap stabilization (not recommended)
 
         For more information read https://arxiv.org/abs/1704.02030
     b_samples: int
@@ -742,7 +742,7 @@ def dict2pd(statdict, labelname):
     statpd = pd.concat(var_dfs, axis=0)
     statpd = statpd.rename(labelname)
     return statpd
-    
+
 def summary(trace, varnames=None, transform=lambda x: x, stat_funcs=None,
                extend=False, include_transformed=False,
                alpha=0.05, start=0, batches=None):
@@ -851,7 +851,7 @@ def summary(trace, varnames=None, transform=lambda x: x, stat_funcs=None,
             funcs = funcs + stat_funcs
         else:
             funcs = stat_funcs
-            
+
     var_dfs = []
     for var in varnames:
         vals = transform(trace.get_values(var, burn=start, combine=True))
@@ -860,21 +860,21 @@ def summary(trace, varnames=None, transform=lambda x: x, stat_funcs=None,
         var_df.index = ttab.create_flat_names(var, vals.shape[1:])
         var_dfs.append(var_df)
     dforg = pd.concat(var_dfs, axis=0)
-    
+
     if (stat_funcs is not None) and (not extend):
         return dforg
     elif trace.nchains < 2:
         return dforg
     else:
-        n_eff = pm.effective_n(trace, 
-                               varnames=varnames, 
+        n_eff = pm.effective_n(trace,
+                               varnames=varnames,
                                include_transformed=include_transformed)
         n_eff_pd = dict2pd(n_eff, 'n_eff')
-        rhat = pm.gelman_rubin(trace, 
-                               varnames=varnames, 
+        rhat = pm.gelman_rubin(trace,
+                               varnames=varnames,
                                include_transformed=include_transformed)
         rhat_pd = dict2pd(rhat, 'Rhat')
-        return pd.concat([dforg, n_eff_pd, rhat_pd], 
+        return pd.concat([dforg, n_eff_pd, rhat_pd],
                          axis=1, join_axes=[dforg.index])
 
 

pymc3/util.py

@@ -10,8 +10,8 @@ def escape_latex(strng):
 
     Implementation taken from the IPython magic `format_latex`
 
-    Example
-    -------
+    Examples
+    --------
         escape_latex('disease_rate')  # 'disease\_rate'
 
     Parameters