[Enh] Activating numpydoc validation during Sphinx build (#694)

* Added patch to avoid error if properties have docstrings, when using numpydoc docstring validation

* Enabled numpydoc validation for basic docstring structure

* Fixes for GL02 and GL03, concerning extra line breaks within or at the end of the docstring

* Fixes for GL06, concerning wrong naming and typos in the main docstring sections

* Fixes for GL07, concerning the wrong order of the docstring sections

* Fixes for SS03, concerning missing period at the end of the summary (first) sentence.

* Fixes for SA02, concerning missing periods at the end of the entries in See Also section.

* Fixes for PR02, concerning missing parameters in the docstring (also catches missing space between parameter name and separator :).

* Fixes for PR05, concerning periods at the end of the parameter type

* Fixes for PR06, concerning wrong parameter types

* Fixes related to GL01, concerning missing line-break from the triple quote token

* Added GL05, concerning tabs instead of spaces in indentations

* Added SS02 and SS04, concerning summary starting with capital letter and no leading spaces

* Fixes for PR03, concerning matching the order of parameters in the docstring to the order in the function signature

* Fixes for PR08, concerning parameter description not starting with a capital letter.

* Comment on PR09, that cannot be used due to the information on defaults

* Added PR10, concerning missing space between the colon separator in the parameter type specification

* Fixes for SA03, concerning See Also descriptions not starting with capital letter.

* Added PR07, for checking undocumented parameters.

* Fixes for RT04, concerning that the description of returns start with a capital letter.

* Fixes for RT05, concerning that the description of returns ends with a period.

* Fixed warnings due to indentations in the window parameter description

* Fixed warnings due to indentations in the description of instantaneous_rate returns

* Added GL01, with remarks for expected warnings.

* Fixed issues related to RT05, concerning the lack of a period at the end of the description of returns.

* Fixed typo in doc/conf.py

Co-authored-by: Harris Jos <104043391+CozySocksAlways@users.noreply.github.com>

---------

Co-authored-by: Harris Jos <104043391+CozySocksAlways@users.noreply.github.com>

Author: kohlerca

doc/conf.py

@@ -21,6 +21,26 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 sys.path.insert(0, '..')
 
+# -- numpydoc validation compatibility patch -----------------------------
+# Property descriptors do not always expose __module__.  numpydoc's
+# `mangle_docstrings` function that is run during the builtin validation
+# accesses `obj.__module__` unconditionally, which raises AttributeError for
+# such objects. This patch must be applied here (before Sphinx loads the
+# extensions) so that when numpydoc.setup() registers its handler, the patched
+# version is used.
+import numpydoc.numpydoc as _numpydoc_mod
+
+_orig_mangle_docstrings = _numpydoc_mod.mangle_docstrings
+
+
+def _safe_mangle_docstrings(app, what, name, obj, options, lines):
+    if not hasattr(obj, '__module__'):
+        return
+    return _orig_mangle_docstrings(app, what, name, obj, options, lines)
+
+
+_numpydoc_mod.mangle_docstrings = _safe_mangle_docstrings
+
 # -- General configuration -----------------------------------------------
 # If your documentation needs a minimal Sphinx version, state it here.
 # needs_sphinx = '1.0'
@@ -210,10 +230,34 @@
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'elephantdoc'
 
+# --- Options for numpydoc ---------------------------------------------
+
+# Validation checks not included:
+# - PR09: warnings triggered by the use of "Default: x" in the last line of
+#   parameter descriptions, which is a common and recommended way to specify
+#   the default and is more readable without a trailing period.
+
+# Notes:
+# - GL01: warnings are triggered for GPFA methods and statistics.cv due to
+#   non-conforming docstrings in sklearn and SciPy that are inherited.
+# - RT05: added in-line exceptions to suppress warnings triggered for functions
+#   in `phase_analysis` where a trailing period is not used in the last line
+#   stating the range of the returned values.
+
+numpydoc_validation_checks = {
+    "GL01", "GL02", "GL03", "GL05", "GL06", "GL07",
+    "SS02", "SS03", "SS04",
+    "SA02", "SA03",
+    "PR02", "PR03", "PR05", "PR06", "PR07", "PR08", "PR10",
+    "RT04", "RT05",
+}
+
 # Suppresses  wrong numpy doc warnings
 # see here https://github.com/phn/pytpm/issues/3#issuecomment-12133978
 numpydoc_show_class_members = False
 
+# --- Options for bibtex -----------------------------------------------
+
 # path to bibtex-bibfiles.
 bibtex_bibfiles = ['bib/elephant.bib']
 

elephant/asset/asset.py

@@ -420,7 +420,6 @@ def _stretched_metric_2d(x, y, stretch, ref_angle, working_memory=None,
     MemoryError
         If there is not enough memory to allocate the matrix to store the
         pairwise distances when using chunked computations.
-
     """
     alpha = np.deg2rad(ref_angle)  # reference angle in radians
 
@@ -1482,8 +1481,7 @@ def synchronous_events_intersection(sse1, sse2, intersection='linkwise'):
 
     See Also
     --------
-    ASSET.extract_synchronous_events : extract SSEs from given spike trains
-
+    ASSET.extract_synchronous_events : Extract SSEs from given spike trains.
     """
     sse_new = sse1.copy()
     for pixel1 in sse1.keys():
@@ -1550,8 +1548,7 @@ def synchronous_events_difference(sse1, sse2, difference='linkwise'):
 
     See Also
     --------
-    ASSET.extract_synchronous_events : extract SSEs from given spike trains
-
+    ASSET.extract_synchronous_events : Extract SSEs from given spike trains.
     """
     sse_new = sse1.copy()
     for pixel1 in sse1.keys():
@@ -1592,7 +1589,6 @@ def _remove_empty_events(sse):
     -------
     sse_new : dict
         A copy of `sse` where all empty events have been removed.
-
     """
     sse_new = sse.copy()
     for pixel, link in sse.items():
@@ -1633,8 +1629,7 @@ def synchronous_events_identical(sse1, sse2):
 
     See Also
     --------
-    ASSET.extract_synchronous_events : extract SSEs from given spike trains
-
+    ASSET.extract_synchronous_events : Extract SSEs from given spike trains.
     """
     # Remove empty links from sse11 and sse22, if any
     sse11 = _remove_empty_events(sse1)
@@ -1672,8 +1667,7 @@ def synchronous_events_no_overlap(sse1, sse2):
 
     See Also
     --------
-    ASSET.extract_synchronous_events : extract SSEs from given spike trains
-
+    ASSET.extract_synchronous_events : Extract SSEs from given spike trains.
     """
     # Remove empty links from sse11 and sse22, if any
     sse11 = _remove_empty_events(sse1)
@@ -1722,8 +1716,7 @@ def synchronous_events_contained_in(sse1, sse2):
 
     See Also
     --------
-    ASSET.extract_synchronous_events : extract SSEs from given spike trains
-
+    ASSET.extract_synchronous_events : Extract SSEs from given spike trains.
     """
     # Remove empty links from sse11 and sse22, if any
     sse11 = _remove_empty_events(sse1)
@@ -1774,15 +1767,14 @@ def synchronous_events_contains_all(sse1, sse2):
     bool
         True if `sse1` strictly contains `sse2`.
 
+    See Also
+    --------
+    ASSET.extract_synchronous_events : Extract SSEs from given spike trains.
+
     Notes
     -----
     `synchronous_events_contains_all(sse1, sse2)` is identical to
     `synchronous_events_is_subsequence(sse2, sse1)`.
-
-    See Also
-    --------
-    ASSET.extract_synchronous_events : extract SSEs from given spike trains
-
     """
     return synchronous_events_contained_in(sse2, sse1)
 
@@ -1815,8 +1807,7 @@ def synchronous_events_overlap(sse1, sse2):
 
     See Also
     --------
-    ASSET.extract_synchronous_events : extract SSEs from given spike trains
-
+    ASSET.extract_synchronous_events : Extract SSEs from given spike trains.
     """
     contained_in = synchronous_events_contained_in(sse1, sse2)
     contains_all = synchronous_events_contains_all(sse1, sse2)
@@ -1844,6 +1835,10 @@ def get_neurons_in_sse(sse):
     list
         All neuron IDs present in the SSE, sorted in ascending order.
 
+    See Also
+    --------
+    ASSET.extract_synchronous_events : Extract SSEs from given spike trains.
+
     Examples
     --------
     >>> sse = {(268, 51): {22, 27},
@@ -1857,10 +1852,6 @@ def get_neurons_in_sse(sse):
     >>> neurons = get_neurons_in_sse(sse)
     >>> print(neurons)
     [9, 22, 26, 27, 77, 92]
-
-    See Also
-    --------
-    ASSET.extract_synchronous_events
     """
     all_neurons = []
     for neurons in sse.values():
@@ -1897,6 +1888,10 @@ def get_sse_start_and_end_time_bins(sse):
         the second element corresponds to the second sequence (elements `j`
         in the SSE pixel).
 
+    See Also
+    --------
+    ASSET.extract_synchronous_events : Extract SSEs from given spike trains.
+
     Examples
     --------
     >>> sse = {(268, 51): {22, 27},
@@ -1912,10 +1907,6 @@ def get_sse_start_and_end_time_bins(sse):
     [268, 51]
     >>> print(end)
     [277, 61]
-
-    See Also
-    --------
-    ASSET.extract_synchronous_events
     """
     pixels = list(sse.keys())
     start = list(pixels[0])
@@ -2024,7 +2015,6 @@ class ASSET(object):
         this value.
         Default: 'default'
 
-
     Raises
     ------
     ValueError
@@ -2033,6 +2023,10 @@ class ASSET(object):
 
           fully disjoint.
 
+    See Also
+    --------
+    :class:`elephant.conversion.BinnedSpikeTrain`
+
     Notes
     -----
         To control the verbosity of log messages throughout the ASSET analysis,
@@ -2045,11 +2039,6 @@ class ASSET(object):
         >>> import logging
         >>> from elephant.asset.asset import logger as asset_logger
         >>> asset_logger.setLevel(logging.WARNING)
-
-    See Also
-    --------
-    :class:`elephant.conversion.BinnedSpikeTrain`
-
     """
 
     def __init__(self, spiketrains_i, spiketrains_j=None, bin_size=3 * pq.ms,
@@ -2131,8 +2120,8 @@ def is_symmetric(self):
 
         See Also
         --------
-        ASSET.intersection_matrix
-
+        ASSET.intersection_matrix : Generates the intersection matrix from a
+                                    list of spike trains.
         """
         return _quantities_almost_equal(self.x_edges[0], self.y_edges[0])
 
@@ -2173,7 +2162,6 @@ def intersection_matrix(self, normalization=None):
             The floating point intersection matrix of a list of spike trains.
             It has the shape `(n, n)`, where `n` is the number of bins that
             time was discretized in.
-
         """
         imat = _intersection_matrix(self.spiketrains_i, self.spiketrains_j,
                                     self.bin_size,
@@ -2244,16 +2232,15 @@ def probability_matrix_montecarlo(self, n_surrogates, imat=None,
             STRICTLY LOWER than the observed overlap, under the null hypothesis
             of independence of the input spike trains.
 
+        See Also
+        --------
+        ASSET.probability_matrix_analytical : Analytical derivation of the
+                                              matrix.
+
         Notes
         -----
         We recommend playing with `surrogate_dt` parameter to see how it
         influences the result matrix. For this, refer to the ASSET tutorial.
-
-        See Also
-        --------
-        ASSET.probability_matrix_analytical : analytical derivation of the
-                                              matrix
-
         """
         if imat is None:
             # Compute the intersection matrix of the original data
@@ -2559,7 +2546,6 @@ def joint_probability_matrix(self, pmat, filter_shape, n_largest,
            caution -using your built-in Intel graphics card to perform
            computations may make the system unresponsive until the compute
            program terminates.
-
         """
         l, w = filter_shape
 
@@ -2649,10 +2635,12 @@ def mask_matrices(matrices, thresholds):
 
         See Also
         --------
-        ASSET.probability_matrix_montecarlo : for `pmat` generation
-        ASSET.probability_matrix_analytical : for `pmat` generation
-        ASSET.joint_probability_matrix : for `jmat` generation
-
+        ASSET.probability_matrix_montecarlo : For `pmat` generation using a
+                                              Monte Carlo approach using
+                                              surrogate data.
+        ASSET.probability_matrix_analytical : For `pmat` generation using the
+                                              analytical derivation.
+        ASSET.joint_probability_matrix : For `jmat` generation.
         """
         if len(matrices) == 0:
             raise ValueError("Empty list of matrices")
@@ -2766,7 +2754,6 @@ def cluster_matrix_entries(mask_matrix, max_distance, min_neighbors,
         See Also
         --------
         sklearn.cluster.DBSCAN
-
         """
 
         # Don't do anything if mat is identically zero

elephant/causality/granger.py

@@ -189,7 +189,6 @@ def _lag_covariances(signals, dimension, max_lag):
         \tau: lag
 
         C(\tau) = \sum_{i=0}^{N-\tau} x[i]*x^T[\tau+i]
-
     """
     length = np.size(signals[0])
 
@@ -243,7 +242,6 @@ def _yule_walker_matrix(data, dimension, order):
         where 1 \leq i \leq j \leq p. The other entries are determined by
         symmetry.
     lag_covariances : np.ndarray
-
     """
 
     lag_covariances = _lag_covariances(data, dimension, order)
@@ -299,7 +297,6 @@ def _vector_arm(signals, dimension, order):
         ry
     covar_mat : np.ndarray
         covariance matrix of
-
     """
 
     yule_walker_matrix, lag_covariances = \
@@ -473,7 +470,6 @@ def _spectral_factorization(cross_spectrum, num_iterations, term_crit=1e-12):
         factorization
         Default: 1e-12
 
-
     Returns
     ------
     cov_matrix : np.ndarray
@@ -545,7 +541,7 @@ def _spectral_factorization(cross_spectrum, num_iterations, term_crit=1e-12):
 
 def pairwise_granger(signals, max_order, information_criterion='aic'):
     r"""
-    Determine Granger Causality of two time series
+    Determine Granger Causality of two time series.
 
     Parameters
     ----------
@@ -644,7 +640,6 @@ def pairwise_granger(signals, max_order, information_criterion='aic'):
     >>> signals = np.array([x[1:], y]).T  # N x 2 matrix
     >>> pairwise_granger(signals, max_order=1)  # noqa
     Causality(directional_causality_x_y=2.64, directional_causality_y_x=-0.0, instantaneous_causality=0.0, total_interdependence=2.64)
-
     """
     if isinstance(signals, AnalogSignal):
         signals = signals.magnitude
@@ -789,7 +784,8 @@ def pairwise_spectral_granger(signal_i, signal_j, fs=1, nw=4, num_tapers=None,
                               len_segment=None, frequency_resolution=None,
                               overlap=0.5, num_iterations=300,
                               term_crit=1e-12):
-    r"""Determine spectral Granger Causality of two signals.
+    r"""
+    Determine spectral Granger Causality of two signals.
 
     The spectral Granger Causality is obtained through the following steps:
 

elephant/cell_assembly_detection.py

@@ -191,7 +191,6 @@ def cell_assembly_detection(binned_spiketrain, max_lag, reference_lag=2,
     Notes
     -----
     Alias: cad
-
     """
     initial_time = time.time()
 
@@ -599,7 +598,6 @@ def _test_pair(ensemble, spiketrain2, n2, max_lag, size_chunks, reference_lag,
     item_candidate : list of list with two components
         in the first component there are the neurons involved in the assembly,
         in the second there are the correspondent lags.
-
     """
 
     # list with the binned spike trains of the two neurons
@@ -1062,7 +1060,6 @@ def _subgroup_pruning_step(pre_pruning_assembly):
     --------
     final_assembly : list
         contains the assemblies filtered by inclusion
-
     """
 
     # reversing the semifinal_assembly makes the computation quicker
@@ -1140,7 +1137,6 @@ def _raise_errors(binned_spiketrain, max_lag, alpha, min_occurrences,
         if the maximal assembly order is not between 2
         and the number of neurons
         if the time series is too short (less than 100 bins)
-
     """
 
     if not isinstance(binned_spiketrain, conv.BinnedSpikeTrain):