From b6f844045d6c7c9321af5c4588d4593358d7d832 Mon Sep 17 00:00:00 2001
From: Moritz Kern <92092328+Moritz-Alexander-Kern@users.noreply.github.com>
Date: Thu, 16 Feb 2023 10:13:08 +0100
Subject: [PATCH] Fix/docstring warnings (#478)

* fix headings for release notes, elephant versions > 0.10.0

* fixed warnings on build html for asset docstring

* fixed warnings on build html for causality.granger docstring

* fixed warnings on build html for cell_assembly_detection docstring

* more fixes

* fixed indentation errors

* fixed import errors

* Apply suggestions from code review

Co-authored-by: Michael Denker <m.denker@fz-juelich.de>

* removed 'binsize', deprecated, use 'bin_size'

* removed deprecation for __init__

* added template for gpfa

* overline for heading in install.rst

* remove template for gpfa

* increase timeout for urlopen

* remove unused variable

* change context for urlopen

* remove timeout

* fix typo

* add template for GPFA class

* fix math expression

---------

Co-authored-by: Michael Denker <m.denker@fz-juelich.de>
---
 doc/_templates/autosummary/gpfa_class.rst     |   7 ++
 .../spike_train_generation_class.rst          |  30 ++++++
 doc/conf.py                                   | 100 ++++++++++--------
 doc/install.rst                               |   5 +-
 elephant/asset/asset.py                       |  10 +-
 elephant/causality/granger.py                 |  12 ++-
 elephant/cell_assembly_detection.py           |  11 +-
 elephant/conversion.py                        |  14 +--
 elephant/current_source_density.py            |   8 +-
 elephant/datasets.py                          |  13 +--
 elephant/gpfa/gpfa.py                         |  15 +--
 elephant/signal_processing.py                 |  13 +--
 elephant/spade.py                             |  25 ++---
 elephant/spike_train_correlation.py           |  21 ++--
 elephant/spike_train_generation.py            |  12 ++-
 elephant/spike_train_surrogates.py            |   4 +-
 elephant/spike_train_synchrony.py             |  13 ++-
 elephant/unitary_event_analysis.py            |   4 +-
 18 files changed, 183 insertions(+), 134 deletions(-)
 create mode 100644 doc/_templates/autosummary/gpfa_class.rst
 create mode 100644 doc/_templates/autosummary/spike_train_generation_class.rst

diff --git a/doc/_templates/autosummary/gpfa_class.rst b/doc/_templates/autosummary/gpfa_class.rst
new file mode 100644
index 000000000..0c146b266
--- /dev/null
+++ b/doc/_templates/autosummary/gpfa_class.rst
@@ -0,0 +1,7 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :special-members: __contains__,__getitem__,__iter__,__len__,__add__,__sub__,__mul__,__div__,__neg__
+   :members:
diff --git a/doc/_templates/autosummary/spike_train_generation_class.rst b/doc/_templates/autosummary/spike_train_generation_class.rst
new file mode 100644
index 000000000..7dfdd91f2
--- /dev/null
+++ b/doc/_templates/autosummary/spike_train_generation_class.rst
@@ -0,0 +1,30 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+
+   {% block methods %}
+
+   {% if methods %}
+   .. rubric:: {{ _('Methods') }}
+
+   .. autosummary::
+   {% for item in methods %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Attributes') }}
+
+   .. autosummary::
+   {% for item in attributes %}
+   {%- if item not in ["process_operational_time","isi_generator"] %}
+      ~{{ name }}.{{ item }}
+   {%- endif %}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
diff --git a/doc/conf.py b/doc/conf.py
index 1b1b7201d..d5187ff53 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -3,7 +3,8 @@
 # Elephant documentation build configuration file, created by
 # sphinx-quickstart on Wed Feb  5 17:11:26 2014.
 #
-# This file is execfile()d with the current directory set to its containing dir.
+# This file is execfile()d with the current directory set to its containing
+# dir.
 #
 # Note that not all possible configuration values are present in this
 # autogenerated file.
@@ -21,11 +22,11 @@
 sys.path.insert(0, '..')
 
 # -- General configuration -----------------------------------------------
-
 # If your documentation needs a minimal Sphinx version, state it here.
-#needs_sphinx = '1.0'
+# needs_sphinx = '1.0'
 
-# Add any Sphinx extension module names here, as strings. They can be extensions
+# 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',
@@ -43,13 +44,13 @@
 ]
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ['_templates/autosummary']
 
 # The suffix of source filenames.
 source_suffix = '.rst'
 
 # The encoding of source files.
-#source_encoding = 'utf-8-sig'
+# source_encoding = 'utf-8-sig'
 
 # The master toctree document.
 master_doc = 'index'
@@ -75,13 +76,13 @@
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
-#language = None
+# language = None
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
-#today = ''
+# today = ''
 # Else, today_fmt is used as the format for a strftime call.
-#today_fmt = '%B %d, %Y'
+# today_fmt = '%B %d, %Y'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -90,25 +91,26 @@
     '**.ipynb_checkpoints',
 ]
 
-# The reST default role (used for this markup: `text`) to use for all documents.
-#default_role = None
+# The reST default role (used for this markup: `text`) to use for all
+# documents.
+# default_role = None
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
-#add_function_parentheses = True
+# add_function_parentheses = True
 
 # If true, the current module name will be prepended to all description
 # unit titles (such as .. function::).
-#add_module_names = True
+# add_module_names = True
 
 # If true, sectionauthor and moduleauthor directives will be shown in the
 # output. They are ignored by default.
-#show_authors = False
+# show_authors = False
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
 # A list of ignored prefixes for module index sorting.
-#modindex_common_prefix = []
+# modindex_common_prefix = []
 
 # Only execute Jupyter notebooks that have no evaluated cells
 nbsphinx_execute = 'auto'
@@ -129,6 +131,10 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 html_theme = 'alabaster'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
 html_theme_options = {
     'font_family': 'Arial',
     'page_width': '1200px',  # default is 940
@@ -137,11 +143,11 @@
 }
 
 # Add any paths that contain custom themes here, relative to this directory.
-#html_theme_path = []
+# html_theme_path = []
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
-#html_title = None
+# html_title = None
 
 # A shorter title for the navigation bar.  Default is the same as html_title.
 html_short_title = None
@@ -162,30 +168,30 @@
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
-#html_last_updated_fmt = '%b %d, %Y'
+# html_last_updated_fmt = '%b %d, %Y'
 
 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities.
 html_use_smartypants = True
 
 # Custom sidebar templates, maps document names to template names.
-#html_sidebars = {}
+# html_sidebars = {}
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.
-#html_additional_pages = {}
+# html_additional_pages = {}
 
 # If false, no module index is generated.
-#html_domain_indices = True
+# html_domain_indices = True
 
 # If false, no index is generated.
 html_use_index = True
 
 # If true, the index is split into individual pages for each letter.
-#html_split_index = False
+# html_split_index = False
 
 # If true, links to the reST sources are added to the pages.
-#html_show_sourcelink = True
+# html_show_sourcelink = True
 
 # If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
 html_show_sphinx = False
@@ -196,10 +202,10 @@
 # If true, an OpenSearch description file will be output, and all pages will
 # contain a <link> tag referring to it.  The value of this option must be the
 # base URL from which the finished HTML is served.
-#html_use_opensearch = ''
+# html_use_opensearch = ''
 
 # This is the file name suffix for HTML files (e.g. ".xhtml").
-#html_file_suffix = None
+# html_file_suffix = None
 
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'elephantdoc'
@@ -231,7 +237,8 @@
 }
 
 # Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title, author, documentclass [howto/manual]).
+# (source start file, target name, title, author, documentclass
+# [howto/manual]).
 latex_documents = [
     ('index', 'elephant.tex', u'Elephant Documentation',
      authors, 'manual'),
@@ -239,23 +246,23 @@
 
 # The name of an image file (relative to this directory) to place at the top of
 # the title page.
-#latex_logo = None
+# latex_logo = None
 
 # For "manual" documents, if this is true, then toplevel headings are parts,
 # not chapters.
-#latex_use_parts = False
+# latex_use_parts = False
 
 # If true, show page references after internal links.
-#latex_show_pagerefs = False
+# latex_show_pagerefs = False
 
 # If true, show URL addresses after external links.
-#latex_show_urls = False
+# latex_show_urls = False
 
 # Documents to append as an appendix to all manuals.
-#latex_appendices = []
+# latex_appendices = []
 
 # If false, no module index is generated.
-#latex_domain_indices = True
+# latex_domain_indices = True
 
 
 # -- Options for manual page output --------------------------------------
@@ -268,7 +275,7 @@
 ]
 
 # If true, show URL addresses after external links.
-#man_show_urls = False
+# man_show_urls = False
 
 
 # -- Options for Texinfo output ------------------------------------------
@@ -287,13 +294,13 @@
 ]
 
 # Documents to append as an appendix to all manuals.
-#texinfo_appendices = []
+# texinfo_appendices = []
 
 # If false, no module index is generated.
-#texinfo_domain_indices = True
+# texinfo_domain_indices = True
 
 # How to display URL addresses: 'footnote', 'no', or 'inline'.
-#texinfo_show_urls = 'footnote'
+# texinfo_show_urls = 'footnote'
 
 
 # -- Options for Epub output ---------------------------------------------
@@ -306,37 +313,37 @@
 
 # The language of the text. It defaults to the language option
 # or en if the language is not set.
-#epub_language = ''
+# epub_language = ''
 
 # The scheme of the identifier. Typical schemes are ISBN or URL.
-#epub_scheme = ''
+# epub_scheme = ''
 
 # The unique identifier of the text. This can be a ISBN number
 # or the project homepage.
-#epub_identifier = ''
+# epub_identifier = ''
 
 # A unique identification for the text.
-#epub_uid = ''
+# epub_uid = ''
 
 # A tuple containing the cover image and cover page html template filenames.
-#epub_cover = ()
+# epub_cover = ()
 
 # HTML files that should be inserted before the pages created by sphinx.
 # The format is a list of tuples containing the path and title.
-#epub_pre_files = []
+# epub_pre_files = []
 
 # HTML files shat should be inserted after the pages created by sphinx.
 # The format is a list of tuples containing the path and title.
-#epub_post_files = []
+# epub_post_files = []
 
 # A list of files that should not be packed into the epub file.
-#epub_exclude_files = []
+# epub_exclude_files = []
 
 # The depth of the table of contents in toc.ncx.
-#epub_tocdepth = 3
+# epub_tocdepth = 3
 
 # Allow duplicate toc entries.
-#epub_tocdup = True
+# epub_tocdup = True
 
 
 # configuration for intersphinx: refer to Viziphant
@@ -345,6 +352,7 @@
     'numpy': ('https://numpy.org/doc/stable', None)
 }
 
+
 # The name of math_renderer extension for HTML output.
 html_math_renderer = 'mathjax'
 
diff --git a/doc/install.rst b/doc/install.rst
index bae37b2bd..6a85b2331 100644
--- a/doc/install.rst
+++ b/doc/install.rst
@@ -209,9 +209,10 @@ You can have one, both, or none installed in your system.
             unresponsive until the compute program terminates.
 
 .. _no-compile-spade:
-***********
+
+****************************
 Resolving compilation issues
-***********
+****************************
 
 Some modules in Elephant make use of C extensions to speed up computation.
 However, those extensions need to be compiled before use. In some cases, this
diff --git a/elephant/asset/asset.py b/elephant/asset/asset.py
index 73f99c637..ef01067e4 100644
--- a/elephant/asset/asset.py
+++ b/elephant/asset/asset.py
@@ -1975,6 +1975,7 @@ def intersection_matrix(self, normalization=None):
                 * 'intersection': `len(intersection(s_i, s_j))`
                 * 'mean': `sqrt(len(s_1) * len(s_2))`
                 * 'union': `len(union(s_i, s_j))`
+
             Default: None
 
         Returns
@@ -2029,9 +2030,9 @@ def probability_matrix_montecarlo(self, n_surrogates, imat=None,
             If None, the output of :func:`ASSET.intersection_matrix` is used.
             Default: None
         surrogate_method : {'dither_spike_train', 'dither_spikes',
-                            'jitter_spikes',
-                            'randomise_spikes', 'shuffle_isis',
-                            'joint_isi_dithering'}, optional
+            'jitter_spikes', 'randomise_spikes', 'shuffle_isis',
+            'joint_isi_dithering'}, optional
+
             The method to generate surrogate spike trains. Refer to the
             :func:`spike_train_surrogates.surrogates` documentation for more
             information about each surrogate method. Note that some of these
@@ -2305,9 +2306,10 @@ def joint_probability_matrix(self, pmat, filter_shape, n_largest,
         precision : {'float', 'double'}, optional
             Single or double floating-point precision for the resulting `jmat`
             matrix.
-              * `'float'`: 32 bits; the tolerance error is ``≲1e-3``.
 
+              * `'float'`: 32 bits; the tolerance error is ``≲1e-3``.
               * `'double'`: 64 bits; the tolerance error is ``<1e-5``.
+
             Double floating-point precision is typically x4 times slower than
             the single floating-point equivalent.
             Default: 'float'
diff --git a/elephant/causality/granger.py b/elephant/causality/granger.py
index f9fd93a0e..db6b49829 100644
--- a/elephant/causality/granger.py
+++ b/elephant/causality/granger.py
@@ -370,8 +370,10 @@ def pairwise_granger(signals, max_order, information_criterion='aic'):
         Maximal order of autoregressive model.
     information_criterion : {'aic', 'bic'}, optional
         A function to compute the information criterion:
-            `bic` for Bayesian information_criterion,
-            `aic` for Akaike information criterion,
+
+        * `bic` for Bayesian information_criterion,
+        * `aic` for Akaike information criterion,
+
         Default: 'aic'
 
     Returns
@@ -538,8 +540,10 @@ def conditional_granger(signals, max_order, information_criterion='aic'):
         Maximal order of autoregressive model.
     information_criterion : {'aic', 'bic'}, optional
         A function to compute the information criterion:
-            `bic` for Bayesian information_criterion,
-            `aic` for Akaike information criterion,
+
+        * `bic` for Bayesian information_criterion,
+        * `aic` for Akaike information criterion,
+
         Default: 'aic'
 
     Returns
diff --git a/elephant/cell_assembly_detection.py b/elephant/cell_assembly_detection.py
index 7659f2f9d..a23bd7c5e 100644
--- a/elephant/cell_assembly_detection.py
+++ b/elephant/cell_assembly_detection.py
@@ -157,10 +157,13 @@ def cell_assembly_detection(binned_spiketrain, max_lag, reference_lag=2,
         if they appear in the very same configuration.
         Default: False
     bool_times_format : bool, optional
-        .. deprecated:: 0.10.0
-        Has no effect, the returning 'times' are always a quantity array
-        specifying the pattern spike times.
-        Default: None
+
+    .. deprecated:: 0.10.0
+
+       Has no effect, the returning 'times' are always a quantity array
+       specifying the pattern spike times.
+       Default: None
+
     verbose : bool, optional
         Regulates the number of prints given by the method. If true all prints
         are given, otherwise the method does give any prints.
diff --git a/elephant/conversion.py b/elephant/conversion.py
index ecf4b06eb..6ec64a5be 100644
--- a/elephant/conversion.py
+++ b/elephant/conversion.py
@@ -317,6 +317,7 @@ class BinnedSpikeTrain(object):
     -----
     There are four minimal configurations of the optional parameters which have
     to be provided, otherwise a `ValueError` will be raised:
+
       * t_start, n_bins, bin_size
       * t_start, n_bins, t_stop
       * t_start, bin_size, t_stop
@@ -325,7 +326,7 @@ class BinnedSpikeTrain(object):
     If `spiketrains` is a `neo.SpikeTrain` or a list thereof, it is enough to
     explicitly provide only one parameter: `n_bins` or `bin_size`. The
     `t_start` and `t_stop` will be calculated from given `spiketrains` (max
-    `t_start` and min `t_stop` of `neo.SpikeTrain`s).
+    `t_start` and min `t_stop` of `neo.SpikeTrain`s`).
     Missing parameter will be calculated automatically.
     All parameters will be checked for consistency. A corresponding error will
     be raised, if one of the four parameters does not match the consistency
@@ -831,7 +832,7 @@ def to_spike_trains(self, spikes="random", as_array=False,
 
         .. code-block:: python
 
-            BinnedSpikeTrain(binned_st.to_spike_trains()) == binned_st
+           BinnedSpikeTrain(binned_st.to_spike_trains()) == binned_st
 
         The object bin size is stored in resulting
         ``spiketrain.annotations['bin_size']``.
@@ -842,13 +843,12 @@ def to_spike_trains(self, spikes="random", as_array=False,
             Specifies how to generate spikes inside bins.
 
               * "left": align spikes from left to right to have equal inter-
-              spike interval;
-
+                spike interval;
               * "center": align spikes around center to have equal inter-spike
-              interval;
-
+                interval;
               * "random": generate spikes from a homogenous Poisson process;
-              it's the fastest mode.
+                it's the fastest mode.
+
             Default: "random"
         as_array : bool, optional
             If True, numpy arrays are returned; otherwise, wrap the arrays in
diff --git a/elephant/current_source_density.py b/elephant/current_source_density.py
index ca8e269a7..ad46f11cd 100644
--- a/elephant/current_source_density.py
+++ b/elephant/current_source_density.py
@@ -12,9 +12,9 @@
 CSD is also called as Source Localization or Source Imaging in the EEG circles.
 Here are CSD methods for different types of electrode configurations.
 
-- 1D - laminar probe like electrodes.
-- 2D - Microelectrode Array like
-- 3D - UtahArray or multiple laminar probes.
+- 1D -laminar probe like electrodes.
+- 2D -Microelectrode Array like
+- 3D -UtahArray or multiple laminar probes.
 
 The following methods have been implemented so far
 
@@ -85,7 +85,7 @@ def estimate_csd(lfp, coordinates='coordinates', method=None,
     method : string
         Pick a method corresponding to the setup, in this implementation
         For Laminar probe style (1D), use 'KCSD1D' or 'StandardCSD',
-         or 'DeltaiCSD' or 'StepiCSD' or 'SplineiCSD'
+        or 'DeltaiCSD' or 'StepiCSD' or 'SplineiCSD'
         For MEA probe style (2D),  use 'KCSD2D', or 'MoIKCSD'
         For array of laminar probes (3D), use 'KCSD3D'
         Defaults to None
diff --git a/elephant/datasets.py b/elephant/datasets.py
index efedb9b25..c6786a085 100644
--- a/elephant/datasets.py
+++ b/elephant/datasets.py
@@ -65,9 +65,9 @@ def download(url, filepath=None, checksum=None, verbose=True):
         try:
             urlretrieve(url, filename=filepath, reporthook=t.update_to)
         except URLError:
-            urlretrieve(url, filename=filepath, reporthook=t.update_to,
-                        data=ssl._create_unverified_context())
-
+            # do not authenticate SSL certificate
+            ssl._create_default_https_context = ssl._create_unverified_context
+            urlretrieve(url, filename=filepath, reporthook=t.update_to)
     return filepath
 
 
@@ -160,9 +160,10 @@ def download_datasets(repo_path, filepath=None, checksum=None,
         except URLError as error:
             # if verification of SSL certificate fails, do not verify cert
             try:  # try again without certificate verification
-                urlopen(default_url + '/README.md',
-                        context=ssl._create_unverified_context())
-            except HTTPError as http_error:  # e.g. 404:
+                ctx = ssl._create_unverified_context()
+                ctx.check_hostname = True
+                urlopen(default_url + '/README.md')
+            except HTTPError:  # e.g. 404
                 default_url = url_to_root + f"raw/master"
 
             warnings.warn(f"Data URL:{default_url}, error: {error}."
diff --git a/elephant/gpfa/gpfa.py b/elephant/gpfa/gpfa.py
index 94d3fb70d..79b4f7515 100644
--- a/elephant/gpfa/gpfa.py
+++ b/elephant/gpfa/gpfa.py
@@ -36,6 +36,7 @@
 
 .. autosummary::
     :toctree: _toctree/gpfa
+    :template: gpfa_class.rst
 
     GPFA
 
@@ -54,7 +55,7 @@
 Run tutorial interactively:
 
 .. image:: https://mybinder.org/badge.svg
-   :target: https://mybinder.org/v2/gh/NeuralEnsemble/elephant/master
+    :target: https://mybinder.org/v2/gh/NeuralEnsemble/elephant/master
             ?filepath=doc/tutorials/gpfa.ipynb
 
 
@@ -86,7 +87,7 @@
 
 
 class GPFA(sklearn.base.BaseEstimator):
-    """
+    r"""
     Apply Gaussian process factor analysis (GPFA) to spike train data
 
     There are two principle scenarios of using the GPFA analysis, both of which
@@ -161,7 +162,7 @@ class GPFA(sklearn.base.BaseEstimator):
             Currently, only 'rbf' is supported.
         gamma : (1, #latent_vars) np.ndarray
             related to GP timescales of latent variables before
-            orthonormalization by :math:`bin_size / sqrt(gamma)`
+            orthonormalization by :math:`\frac{bin\_size}{\sqrt{gamma}}`
         eps : (1, #latent_vars) np.ndarray
             GP noise variances
         d : (#units, 1) np.ndarray
@@ -191,13 +192,6 @@ class GPFA(sklearn.base.BaseEstimator):
             mapping between the neuronal data space and the orthonormal
             latent variable space
 
-    Methods
-    -------
-    fit
-    transform
-    fit_transform
-    score
-
     Raises
     ------
     ValueError
@@ -242,6 +236,7 @@ class GPFA(sklearn.base.BaseEstimator):
     def __init__(self, bin_size=20 * pq.ms, x_dim=3, min_var_frac=0.01,
                  tau_init=100.0 * pq.ms, eps_init=1.0E-3, em_tol=1.0E-8,
                  em_max_iters=500, freq_ll=5, verbose=False):
+        # Initialize object
         self.bin_size = bin_size
         self.x_dim = x_dim
         self.min_var_frac = min_var_frac
diff --git a/elephant/signal_processing.py b/elephant/signal_processing.py
index 0f66754d1..1ead86b64 100644
--- a/elephant/signal_processing.py
+++ b/elephant/signal_processing.py
@@ -419,13 +419,10 @@ def butter(signal, highpass_frequency=None, lowpass_frequency=None, order=4,
         `lowpass_frequency` and `highpass_frequency`:
 
         * `highpass_frequency` only (`lowpass_frequency` is None):
-        highpass filter
-
+           highpass filter
         * `lowpass_frequency` only (`highpass_frequency` is None):
-        lowpass filter
-
+           lowpass filter
         * `highpass_frequency` < `lowpass_frequency`: bandpass filter
-
         * `highpass_frequency` > `lowpass_frequency`: bandstop filter
 
         Default: None
@@ -436,9 +433,7 @@ def butter(signal, highpass_frequency=None, lowpass_frequency=None, order=4,
         Filtering function to be used. Available filters:
 
         * 'filtfilt': `scipy.signal.filtfilt`;
-
         * 'lfilter': `scipy.signal.lfilter`;
-
         * 'sosfiltfilt': `scipy.signal.sosfiltfilt`.
 
         In most applications 'filtfilt' should be used, because it doesn't
@@ -890,8 +885,8 @@ def rauc(signal, baseline=None, bin_duration=None, t_start=None, t_stop=None):
         If None, ends at the last time of `signal`.
         The signal is cropped using `signal.time_slice(t_start, t_stop)` after
         baseline removal. Useful if you want the RAUC for a short section of
-        the signal but want the mean or median calculation (`baseline`='mean'
-        or `baseline`='median') to use the entire signal for better baseline
+        the signal but want the mean or median calculation (`baseline` ='mean'
+        or `baseline` ='median') to use the entire signal for better baseline
         estimation.
         Default: None
 
diff --git a/elephant/spade.py b/elephant/spade.py
index 40192bfc0..73a3bf00d 100644
--- a/elephant/spade.py
+++ b/elephant/spade.py
@@ -48,7 +48,7 @@
 
 See Also
 --------
-:doc:`cell_assembly_detection`: another synchronous
+elephant.cell_assembly_detection.cell_assembly_detection : another synchronous
 patterns detection
 
 
@@ -74,11 +74,8 @@
 
 >>> patterns = spade(spiketrains, bin_size=10 * pq.ms, winlen=1,
 ...                  dither=5 * pq.ms, min_spikes=6, n_surr=10,
-...                  psr_param=[0, 0, 3])['patterns']  # doctest:+ELLIPSIS
-Time for data mining: ...
-Time for pvalue spectrum computation: ...
-
->>> patterns[0] # doctest: +SKIP
+...                  psr_param=[0, 0, 3])['patterns']
+>>> patterns[0]
 {'itemset': (4, 3, 0, 2, 5, 1),
  'windows_ids': (9,
   16,
@@ -193,7 +190,7 @@ def spade(spiketrains, bin_size, winlen, min_spikes=2, min_occ=2,
         pattern. If None, no maximal number of occurrences is considered.
         Default: None
     min_neu : int, optional
-        Minimum number of neurons in a sequence to considered a pattern.
+        Minimum number of neurons in a sequence to consider a pattern.
         Default: 1
     approx_stab_pars : dict or None, optional
         Parameter values for approximate stability computation.
@@ -282,12 +279,14 @@ def spade(spiketrains, bin_size, winlen, min_spikes=2, min_occ=2,
 
             If `output_format` is 'concepts', then `output['patterns']` is a
             tuple of patterns which in turn are tuples of
+
                 1. spikes in the pattern
                 2. occurrences of the pattern
 
             For details see :func:`concepts_mining`.
 
             if stability is calculated, there are also:
+
                 3. intensional stability
                 4. extensional stability
 
@@ -315,19 +314,9 @@ def spade(spiketrains, bin_size, winlen, min_spikes=2, min_occ=2,
 
     >>> from elephant.spade import spade
     >>> import quantities as pq
-    >>> from elephant.spike_train_generation import compound_poisson_process
-
-    >>> np.random.seed(30)
-    >>> spiketrains = compound_poisson_process(rate=15*pq.Hz,
-    ...     amplitude_distribution=[0, 0.95, 0, 0, 0, 0, 0.05], t_stop=5*pq.s)
-
     >>> bin_size = 3 * pq.ms # time resolution to discretize the spiketrains
     >>> winlen = 10 # maximal pattern length in bins (i.e., sliding window)
-
-    >>> result_spade = spade(
-    ...                     spiketrains, bin_size, winlen) # doctest: +ELLIPSIS
-    Time for data mining: ...
-
+    >>> result_spade = spade(spiketrains, bin_size, winlen)
 
     """
     if HAVE_MPI:  # pragma: no cover
diff --git a/elephant/spike_train_correlation.py b/elephant/spike_train_correlation.py
index 8d2a98908..23294862f 100644
--- a/elephant/spike_train_correlation.py
+++ b/elephant/spike_train_correlation.py
@@ -329,7 +329,7 @@ def covariance(binned_spiketrain, binary=False, fast=True):
         When using `fast=True` and `binned_spiketrain` shape is large.
 
     Warns
-    --------
+    -----
     UserWarning
         If at least one row in `binned_spiketrain` is empty (has no spikes).
 
@@ -438,7 +438,7 @@ def correlation_coefficient(binned_spiketrain, binary=False, fast=True):
         When using `fast=True` and `binned_spiketrain` shape is large.
 
     Warns
-    --------
+    -----
     UserWarning
         If at least one row in `binned_spiketrain` is empty (has no spikes).
 
@@ -562,6 +562,7 @@ def cross_correlation_histogram(
     """
     Computes the cross-correlation histogram (CCH) between two binned spike
     trains `binned_spiketrain_i` and `binned_spiketrain_j`.
+    :cite:`correlation-Eggermont2010_77`
 
     Visualization of this function is covered in Viziphant:
     :func:`viziphant.spike_train_correlation.plot_cross_correlation_histogram`.
@@ -574,18 +575,18 @@ def cross_correlation_histogram(
         spike trains can have any `t_start` and `t_stop`.
     window : {'valid', 'full'} or list of int, optional
         ‘full’: This returns the cross-correlation at each point of overlap,
-                with an output shape of (N+M-1,). At the end-points of the
-                cross-correlogram, the signals do not overlap completely, and
-                boundary effects may be seen.
+              with an output shape of (N+M-1,). At the end-points of the
+              cross-correlogram, the signals do not overlap completely, and
+              boundary effects may be seen.
         ‘valid’: Mode valid returns output of length max(M, N) - min(M, N) + 1.
-                 The cross-correlation product is only given for points where
-                 the signals overlap completely.
-                 Values outside the signal boundary have no effect.
+              The cross-correlation product is only given for points where
+              the signals overlap completely.
+              Values outside the signal boundary have no effect.
         List of integers (min_lag, max_lag):
               The entries of window are two integers representing the left and
               right extremes (expressed as number of bins) where the
               cross-correlation is computed.
-        Default: 'full'
+    Default: 'full'
     border_correction : bool, optional
         whether to correct for the border effect. If True, the value of the
         CCH at bin :math:`b` (for :math:`b=-H,-H+1, ...,H`, where :math:`H` is
@@ -606,10 +607,12 @@ def cross_correlation_histogram(
         smoothing window. The smoothing window cannot be larger than the
         maximum lag of the CCH. The kernel is normalized to unit area before
         being applied to the resulting CCH. Popular choices for the kernel are
+
           * normalized boxcar kernel: `numpy.ones(N)`
           * hamming: `numpy.hamming(N)`
           * hanning: `numpy.hanning(N)`
           * bartlett: `numpy.bartlett(N)`
+
         If None, the CCH is not smoothed.
         Default: None
     method : {'speed', 'memory'}, optional
diff --git a/elephant/spike_train_generation.py b/elephant/spike_train_generation.py
index 1ed0be30e..26078005b 100644
--- a/elephant/spike_train_generation.py
+++ b/elephant/spike_train_generation.py
@@ -17,6 +17,7 @@
 ****************************
 .. autosummary::
     :toctree: _toctree/spike_train_generation
+    :template: spike_train_generation_class.rst
 
     StationaryPoissonProcess
     StationaryGammaProcess
@@ -267,7 +268,9 @@ def peak_detection(signal, threshold=0.0 * pq.mV, sign='above',
         of a (default) `neo.SpikeTrain` object.
         Default: False
     format : {None, 'raw'}, optional
+
         .. deprecated:: 0.8.0
+
         Whether to return as SpikeTrain (None) or as a plain array of times
         ('raw').
         Deprecated. Use `as_array=False` for None format and `as_array=True`
@@ -575,8 +578,8 @@ class StationaryPoissonProcess(RenewalProcess):
     """
     Generates spike trains whose spikes are realizations of a stationary
     Poisson process with the given rate, starting at time `t_start` and
-    stopping at time `t_stop`. Optionally, a absolute refractory period /
-    dead time can be specified.
+    stopping at time `t_stop` :cite:`generation-Deger12_443`. Optionally,
+    an absolute refractory period / dead time can be specified.
 
     Parameters
     ----------
@@ -1344,11 +1347,13 @@ def single_interaction_process(
         Overall mean rate of the time series to be generated (coincidence
         rate `coincidence_rate` is subtracted to determine the background
         rate). Can be:
+
         * a float, representing the overall mean rate of each process. If
           so, it must be higher than `coincidence_rate`.
         * an iterable of floats (one float per process), each float
           representing the overall mean rate of a process. If so, all the
           entries must be larger than `coincidence_rate`.
+
     coincidence_rate : pq.Quantity
         Coincidence rate (rate of coincidences for the n-dimensional SIP).
         The SIP spike trains will have coincident events with rate
@@ -1370,9 +1375,10 @@ def single_interaction_process(
         istic (i.e. rate_coincidence is the actual rate with which coincidences
         are generated) or stochastic (i.e. rate_coincidence is the mean rate of
         coincidences):
-          * 'deterministic': deterministic rate
 
+          * 'deterministic': deterministic rate
           * 'stochastic': stochastic rate
+
         Default: 'deterministic'
     t_start : pq.Quantity, optional
         Starting time of the series. If specified, it must be lower than
diff --git a/elephant/spike_train_surrogates.py b/elephant/spike_train_surrogates.py
index 0565c76d3..189257924 100644
--- a/elephant/spike_train_surrogates.py
+++ b/elephant/spike_train_surrogates.py
@@ -768,7 +768,7 @@ class JointISI(object):
         Default: False
     method : {'fast', 'window'}, optional
         * 'fast': the spike can move in the whole range between the
-            previous and subsequent spikes (computationally efficient).
+           previous and subsequent spikes (computationally efficient).
         * 'window': the spike movement is limited to the parameter `dither`.
 
         Default: 'window'
@@ -1029,7 +1029,7 @@ def dithering(self, n_surrogates=1):
             Default: 1
 
         Returns
-        ----------
+        -------
         dithered_sts : list of neo.SpikeTrain
             Spike trains, that are dithered versions of the given
             :attr:`spiketrain`.
diff --git a/elephant/spike_train_synchrony.py b/elephant/spike_train_synchrony.py
index 9fdf5243e..938e954e4 100644
--- a/elephant/spike_train_synchrony.py
+++ b/elephant/spike_train_synchrony.py
@@ -87,7 +87,7 @@ def spike_contrast(spiketrains, t_start=None, t_stop=None,
         A list of input spike trains to calculate the synchrony from.
     t_start : pq.Quantity, optional
         The beginning of the spike train. If None, it's taken as the minimum
-        value of `t_start`s of the input spike trains.
+        value of `t_start` values of the input spike trains.
         Default: None
     t_stop : pq.Quantity, optional
         The end of the spike train. If None, it's taken as the maximum value
@@ -286,22 +286,26 @@ def delete_synchrofacts(self, threshold, in_place=False, mode='delete'):
         threshold : int
             Threshold value for the deletion of spikes engaged in synchronous
             activity.
+
               * `deletion_threshold >= 2` leads to all spikes with a larger or
-                equal complexity value to be deleted/extracted.
+                 equal complexity value to be deleted/extracted.
               * `deletion_threshold <= 1` leads to a ValueError, since this
-              would delete/extract all spikes and there are definitely more
-              efficient ways of doing so.
+                 would delete/extract all spikes and there are definitely more
+                 efficient ways of doing so.
+
         in_place : bool, optional
             Determines whether the modification are made in place
             on ``self.input_spiketrains``.
             Default: False
         mode : {'delete', 'extract'}, optional
             Inversion of the mask for deletion of synchronous events.
+
               * ``'delete'`` leads to the deletion of all spikes with
                 complexity >= `threshold`,
                 i.e. deletes synchronous spikes.
               * ``'extract'`` leads to the deletion of all spikes with
                 complexity < `threshold`, i.e. extracts synchronous spikes.
+
             Default: 'delete'
 
         Raises
@@ -316,6 +320,7 @@ def delete_synchrofacts(self, threshold, in_place=False, mode='delete'):
         list of neo.SpikeTrain
             List of spiketrains where the spikes with
             ``complexity >= threshold`` have been deleted/extracted.
+
               * If ``in_place`` is True, the returned list is the same as
                 ``self.input_spiketrains``.
               * If ``in_place`` is False, the returned list is a deepcopy of
diff --git a/elephant/unitary_event_analysis.py b/elephant/unitary_event_analysis.py
index ab68f733b..e83a0e2cf 100644
--- a/elephant/unitary_event_analysis.py
+++ b/elephant/unitary_event_analysis.py
@@ -727,15 +727,15 @@ def jointJ_window_analysis(spiketrains, bin_size=5 * pq.ms,
         Default: None
     method : str, optional
         The method with which to compute the unitary events:
+
           * 'analytic_TrialByTrial': calculate the analytical expectancy
             on each trial, then sum over all trials;
-
           * 'analytic_TrialAverage': calculate the expectancy by averaging over
             trials (cf. Gruen et al. 2003);
-
           * 'surrogate_TrialByTrial': calculate the distribution of expected
             coincidences by spike time randomization in each trial and sum over
             trials.
+
         Default: 'analytic_trialByTrial'
     t_start, t_stop : float or pq.Quantity, optional
         The start and stop times to use for the time points.