Documentation build failure

[sanjayankur31]

With the 0.6.2 release, and the latest git snapshot, the package documentation does not build. To verify, I tested it out in a clean python 3 virtual environment where I installed all the required deps from the requirements*.txt files:

$ git log
commit 61b9fd0817063b4ed77c9dc406241ea73f0dcdc8 (HEAD -> master, origin/master, origin/HEAD)
..

$ pip freeze
alabaster==0.7.12
Babel==2.7.0
certifi==2019.3.9
chardet==3.0.4
docutils==0.14
elephant==0.6.2
idna==2.8
imagesize==1.1.0
Jinja2==2.10.1
joblib==0.13.2
MarkupSafe==1.1.1
neo==0.7.1
nose==1.3.7
numpy==1.16.4
numpydoc==0.9.1
packaging==19.0
pandas==0.24.2
Pygments==2.4.2
pyparsing==2.4.0
python-dateutil==2.8.0
pytz==2019.1
quantities==0.12.3
requests==2.22.0
scikit-learn==0.21.2
scipy==1.3.0
six==1.12.0
snowballstemmer==1.2.1
Sphinx==2.1.1
sphinxcontrib-applehelp==1.0.1
sphinxcontrib-devhelp==1.0.1
sphinxcontrib-htmlhelp==1.0.2
sphinxcontrib-jsmath==1.0.1
sphinxcontrib-qthelp==1.0.2
sphinxcontrib-serializinghtml==1.1.3
urllib3==1.25.3

$ make html
sphinx-build -b html -d _build/doctrees   . _build/html
Running Sphinx v2.1.1
making output directory... done
loading intersphinx inventory from http://docs.python.org/objects.inv...
intersphinx inventory has moved: http://docs.python.org/objects.inv -> https://docs.python.org/3/objects.inv
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 26 source files that are out of date
updating environment: 26 added, 0 changed, 0 removed
/home/asinha/dump/py3-virts/elephant/lib64/python3.7/site-packages/numpydoc/docscrape.py:424: UserWarning: Unknown section Example in the docstring of <function joint_probability_matrix at 0x7fbfb0c3f0d0> in ../elephant/asset.py.
  warn(msg)

Exception occurred:
  File "/home/asinha/dump/py3-virts/elephant/lib64/python3.7/site-packages/numpydoc/docscrape.py", line 330, in _parse_see_also
    raise ParseError("%s is not a item name" % line)
numpydoc.docscrape.ParseError: probability_matrix_analytical() for analytical derivation of the matrix is not a item name in "Given a list of parallel spike trains, estimate the cumulative probability\n of each entry in their intersection matrix (see: intersection_matrix())\nby a Monte Carlo approach using surrogate data.\nContrarily to the analytical version (see: probability_matrix_analytical())\nthe Monte Carlo one does not incorporate the assumptions of Poissonianity\nin the null hypothesis.\n\nThe method produces surrogate spike trains (using one of several methods\nat disposal, see below) and calculates their intersection matrix M.\nFor each entry (i, j), the intersection cdf P[i, j] is then given by:\n\n.. centered::  P[i, j] = #(spike_train_surrogates such that M[i, j] < I[i, j]) /\n                    #(spike_train_surrogates)\n\nIf P[i, j] is large (close to 1), I[i, j] is statistically significant:\nthe probability to observe an overlap equal to or larger then I[i, j]\nunder the null hypothesis is 1-P[i, j], very small.\n\nParameters\n----------\nsts : list of neo.SpikeTrains\n    list of spike trains for which to compute the probability matrix\nbinsize : quantities.Quantity\n    width of the time bins used to compute the probability matrix\ndt : quantities.Quantity\n    time span for which to consider the given SpikeTrains\nt_start_x, t_start_y : quantities.Quantity, optional\n    time start of the binning for the first and second axes of the\n    intersection matrix, respectively.\n    If None (default) the attribute t_start of the SpikeTrains is used\n    (if the same for all spike trains).\n    Default: None\nsurr_method : str, optional\n    the method to use to generate surrogate spike trains. Can be one of:\n\n        * 'dither_spike_train': see spike_train_surrogates.train_shifting() [dt needed]\n        * 'spike_dithering': see spike_train_surrogates.spike_dithering() [dt needed]\n        * 'spike_jittering': see spike_train_surrogates.spike_jittering() [dt needed]\n        * 'spike_time_rand': see spike_train_surrogates.spike_time_rand()\n        * 'isi_shuffling': see spike_train_surrogates.isi_shuffling()\n\n    Default: 'dither_spike_train'\nj : quantities.Quantity, optional\n    For methods shifting spike times randomly around their original time\n    (spike dithering, train shifting) or replacing them randomly within a\n    certain window (spike jittering), j represents the size of that\n    shift / window. For other methods, j is ignored.\n    Default: None\nn_surr : int, optional\n    number of spike_train_surrogates to generate for the bootstrap\n    procedure. Default: 100\n\nReturns\n-------\npmat : ndarray\n    the cumulative probability matrix. pmat[i, j] represents the\n    estimated probability of having an overlap between bins i and j\n    STRICTLY LOWER than the observed overlap, under the null hypothesis\n    of independence of the input spike trains.\n\nSee also\n--------\nprobability_matrix_analytical() for analytical derivation of the matrix"
The full traceback has been saved in /tmp/sphinx-err-nju1wph1.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!
make: *** [Makefile:45: html] Error 2
(ins)(elephant) [asinha@ankur-pc  doc(master=)]$

We receive the same error on the Fedora builds also.

$ python --version
Python 3.7.3

[dizcza]

The fix in #230 introduces another issue that will be fixed in
#232.