[fix] Add docstring and parameter formatting improvements (#766)

* Add docstring and parameter formatting improvements

Improved docstring formatting and parameter documentation in _delay.py and slow_points.py for better clarity and consistency. No functional changes were made to the code logic.

* Revert "Add docstring and parameter formatting improvements"

This reverts commit d3fdde2.

* Fix docstring formatting issues in sphinx build

- Convert docstring section headers from rst underline format to :: format
- Fixes sphinx_autodoc_typehints extension errors
- Only modify the problematic Examples, Parameters, Returns sections
- Affects 21 core files with docstring formatting issues

* Update docstring parameter sections to use 'Parameters::'

Replaces NumPy-style 'Parameters' and 'Returns' docstring sections (using '----------') with reStructuredText-style 'Parameters::' and 'Returns::' across multiple modules. This improves consistency and compatibility with documentation tools that expect reST formatting.

Author: Routhleck

brainpy/_src/_delay.py

@@ -34,8 +34,8 @@ class Delay(DynamicalSystem):
        delay = length-1        data
        delay = length          data ]
 
-  Parameters
-  ----------
+  Parameters::
+
   latest: Variable
     The initial delay data.
   length: int
@@ -221,8 +221,8 @@ def _check_delay(self, delay_len):
   def retrieve(self, delay_step, *indices):
     """Retrieve the delay data according to the delay length.
 
-    Parameters
-    ----------
+    Parameters::
+
     delay_step: int, ArrayType
       The delay length used to retrieve the data.
     """

brainpy/_src/analysis/highdim/slow_points.py

@@ -46,8 +46,8 @@ class SlowPointFinder(base.DSAnalyzer):
   - exclude any non-unique fixed points according to a tolerance
   - exclude any far-away "outlier" fixed points
 
-  Parameters
-  ----------
+  Parameters::
+
   f_cell : callable, function, DynamicalSystem
     The target of computing the recurrent units.
 
@@ -307,8 +307,8 @@ def find_fps_with_gd_method(
   ):
     """Optimize fixed points with gradient descent methods.
 
-    Parameters
-    ----------
+    Parameters::
+
     candidates : ArrayType, dict
       The array with the shape of (batch size, state dim) of hidden states
       of RNN to start training for fixed points.
@@ -409,8 +409,8 @@ def find_fps_with_opt_solver(
   ):
     """Optimize fixed points with nonlinear optimization solvers.
 
-    Parameters
-    ----------
+    Parameters::
+
     candidates: ArrayType, dict
       The candidate (initial) fixed points.
     opt_solver: str
@@ -453,8 +453,8 @@ def find_fps_with_opt_solver(
   def filter_loss(self, tolerance: float = 1e-5):
     """Filter fixed points whose speed larger than a given tolerance.
 
-    Parameters
-    ----------
+    Parameters::
+
     tolerance: float
       Discard fixed points with squared speed larger than this value.
     """
@@ -478,8 +478,8 @@ def filter_loss(self, tolerance: float = 1e-5):
   def keep_unique(self, tolerance: float = 2.5e-2):
     """Filter unique fixed points by choosing a representative within tolerance.
 
-    Parameters
-    ----------
+    Parameters::
+
     tolerance: float
       Tolerance for determination of identical fixed points.
     """
@@ -500,8 +500,8 @@ def keep_unique(self, tolerance: float = 2.5e-2):
   def exclude_outliers(self, tolerance: float = 1e0):
     """Exclude points whose closest neighbor is further than threshold.
 
-    Parameters
-    ----------
+    Parameters::
+
     tolerance: float
       Any point whose closest fixed point is greater than tol is an outlier.
     """
@@ -545,8 +545,8 @@ def compute_jacobians(
   ):
     """Compute the Jacobian matrices at the points.
 
-    Parameters
-    ----------
+    Parameters::
+
     points: np.ndarray, bm.ArrayType, jax.ndarray
       The fixed points with the shape of (num_point, num_dim).
     stack_dict_var: bool
@@ -605,17 +605,17 @@ def compute_jacobians(
   def decompose_eigenvalues(matrices, sort_by='magnitude', do_compute_lefts=False):
     """Compute the eigenvalues of the matrices.
 
-    Parameters
-    ----------
+    Parameters::
+
     matrices: np.ndarray, bm.ArrayType, jax.ndarray
       A 3D array with the shape of (num_matrices, dim, dim).
     sort_by: str
       The method of sorting.
     do_compute_lefts: bool
       Compute the left eigenvectors? Requires a pseudo-inverse call.
 
-    Returns
-    -------
+    Returns::
+
     decompositions : list
       A list of dictionaries with sorted eigenvalues components:
       (eigenvalues, right eigenvectors, and left eigenvectors).

brainpy/_src/analysis/lowdim/lowdim_analyzer.py

@@ -39,8 +39,8 @@ class LowDimAnalyzer(DSAnalyzer):
   .. note::
     ``LowDimAnalyzer`` cannot analyze dynamical system depends on time :math:`t`.
 
-  Parameters
-  ----------
+  Parameters::
+
   model : Any, ODEIntegrator, sequence of ODEIntegrator, DynamicalSystem
       A model of the population, the integrator function,
       or a list/tuple of integrator functions.
@@ -346,15 +346,14 @@ def _get_fixed_points(self, candidates, *args, num_seg=None, tol_aux=1e-7, loss_
     >>>     all_par1.append(jnp.ones_like(xs) * p1)
     >>>     all_par2.append(jnp.ones_like(xs) * p2)
 
-    Parameters
-    ----------
+    Parameters::
+
     candidates
     args
     tol_aux
     loss_screen
 
-    Returns
-    -------
+    Returns::
 
     """
     # candidates: xs, a vector with the length of self.resolutions[self.x_var]
@@ -913,8 +912,8 @@ def _get_fixed_points(self, candidates, *args, tol_aux=1e-7,
     >>>     all_par1.append(jnp.ones_like(nullcline_points) * p1)
     >>>     all_par2.append(jnp.ones_like(nullcline_points) * p2)
 
-    Parameters
-    ----------
+    Parameters::
+
     candidates: np.ndarray, jnp.ndarray
       The candidate points (batched) to optimize, like the nullcline points.
     args : tuple
@@ -923,8 +922,8 @@ def _get_fixed_points(self, candidates, *args, tol_aux=1e-7,
     tol_unique : float
     tol_opt_candidate : float, optional
 
-    Returns
-    -------
+    Returns::
+
     res : tuple
       The fixed point results.
     """

brainpy/_src/analysis/lowdim/lowdim_bifurcation.py

@@ -174,8 +174,8 @@ def plot_bifurcation(self, with_plot=True, show=False, with_return=False,
                        select_candidates='aux_rank', num_rank=100):
     """Make the bifurcation analysis.
 
-    Parameters
-    ----------
+    Parameters::
+
     with_plot: bool
       Whether plot the bifurcation figure.
     show: bool
@@ -211,8 +211,8 @@ def plot_bifurcation(self, with_plot=True, show=False, with_return=False,
       The number of candidates to be used to optimize the fixed points.
       rank to use.
 
-    Returns
-    -------
+    Returns::
+
     results : tuple
       Return a tuple of analyzed results:
 

brainpy/_src/analysis/lowdim/lowdim_phase_plane.py

@@ -27,8 +27,8 @@ class PhasePlane1D(Num1DAnalyzer):
   - Vector fields
   - Fixed points
 
-  Parameters
-  ----------
+  Parameters::
+
   model : Any
       A model of the population, the integrator function,
       or a list/tuple of integrator functions.
@@ -123,8 +123,8 @@ def plot_fixed_point(self, show=False, with_plot=True, with_return=False):
 class PhasePlane2D(Num2DAnalyzer):
   """Phase plane analyzer for 2D dynamical system.
 
-  Parameters
-  ----------
+  Parameters::
+
   model : Any
     A model of the population, the integrator function,
     or a list/tuple of integrator functions.
@@ -169,8 +169,8 @@ def plot_vector_field(self, with_plot=True, with_return=False,
                         plot_method='streamplot', plot_style=None, show=False):
     """Plot the vector field.
 
-    Parameters
-    ----------
+    Parameters::
+
     with_plot: bool
     with_return : bool
     show : bool
@@ -364,8 +364,8 @@ def plot_trajectory(self, initials, duration, plot_durations=None, axes='v-v',
                       dt=None, show=False, with_plot=True, with_return=False, **kwargs):
     """Plot trajectories according to the settings.
 
-    Parameters
-    ----------
+    Parameters::
+
     initials : list, tuple, dict
         The initial value setting of the targets. It can be a tuple/list of floats to specify
         each value of dynamical variables (for example, ``(a, b)``). It can also be a
@@ -460,8 +460,8 @@ def plot_trajectory(self, initials, duration, plot_durations=None, axes='v-v',
   def plot_limit_cycle_by_sim(self, initials, duration, tol=0.01, show=False, dt=None):
     """Plot trajectories according to the settings.
 
-    Parameters
-    ----------
+    Parameters::
+
     initials : list, tuple
         The initial value setting of the targets.
 

brainpy/_src/analysis/stability.py

@@ -83,18 +83,17 @@ def stability_analysis(derivatives):
 
   The analysis is referred to [1]_.
 
-  Parameters
-  ----------
+  Parameters::
+
   derivatives : float, tuple, list, np.ndarray
       The derivative of the f.
 
-  Returns
-  -------
+  Returns::
+
   fp_type : str
       The type of the fixed point.
 
-  References
-  ----------
+  References::
 
   .. [1] http://www.egwald.ca/nonlineardynamics/twodimensionaldynamics.php
 

brainpy/_src/analysis/utils/measurement.py

@@ -47,13 +47,13 @@ def euclidean_distance(points: np.ndarray, num_point=None):
   >>> from scipy.spatial.distance import squareform, pdist
   >>> f = lambda points: squareform(pdist(points, metric="euclidean"))
 
-  Parameters
-  ----------
+  Parameters::
+
   points: ArrayType
     The points.
 
-  Returns
-  -------
+  Returns::
+
   dist_matrix: jnp.ndarray
     The distance matrix.
   """
@@ -94,14 +94,14 @@ def euclidean_distance_jax(points: Union[jnp.ndarray, bm.ndarray], num_point=Non
   >>> from scipy.spatial.distance import squareform, pdist
   >>> f = lambda points: squareform(pdist(points, metric="euclidean"))
 
-  Parameters
-  ----------
+  Parameters::
+
   points: ArrayType
     The points.
   num_point: int
 
-  Returns
-  -------
+  Returns::
+
   dist_matrix: ArrayType
     The distance matrix.
   """

brainpy/_src/analysis/utils/optimization.py

@@ -229,8 +229,8 @@ def scipy_minimize_with_jax(fun, x0,
   """
   A simple wrapper for scipy.optimize.minimize using JAX.
 
-  Parameters
-  ----------
+  Parameters::
+
   fun: function
     The objective function to be minimized, written in JAX code
     so that it is automatically differentiable.  It is of type,
@@ -326,8 +326,8 @@ def scipy_minimize_with_jax(fun, x0,
           ```callback(xk)```
       where `xk` is the current parameter vector, represented as a PyTree.
 
-  Returns
-  -------
+  Returns::
+
   res : The optimization result represented as a ``OptimizeResult`` object.
     Important attributes are:
         ``x``: the solution array, represented as a JAX PyTree
@@ -423,8 +423,8 @@ def numpy_brentq(f, a, b, args=(), xtol=2e-14, maxiter=200, rtol=4 * np.finfo(fl
   Uses the classic Brent's method to find a zero of the function `f` on
   the sign changing interval [a , b].
 
-  Parameters
-  ----------
+  Parameters::
+
   f : callable
       Python function returning a number.  `f` must be continuous.
   a : number
@@ -545,15 +545,15 @@ def numpy_brentq(f, a, b, args=(), xtol=2e-14, maxiter=200, rtol=4 * np.finfo(fl
 def find_root_of_1d_numpy(f, f_points, args=(), tol=1e-8):
   """Find the roots of the given function by numerical methods.
 
-  Parameters
-  ----------
+  Parameters::
+
   f : callable
       The function.
   f_points : np.ndarray, list, tuple
       The value points.
 
-  Returns
-  -------
+  Returns::
+
   roots : list
       The roots.
   """