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

Author: Routhleck

brainpy/_src/connect/base.py

@@ -88,8 +88,8 @@ def set_default_dtype(mat_dtype=None, idx_dtype=None):
          [0., 1., 0., 1.],
          [0., 0., 1., 0.]], dtype=float32)
 
-  Parameters
-  ----------
+  Parameters::
+  
   mat_dtype : type
     The default dtype for connection matrix.
   idx_dtype : type
@@ -173,15 +173,15 @@ def __repr__(self):
   def __call__(self, pre_size, post_size):
     """Create the concrete connections between two end objects.
 
-    Parameters
-    ----------
+    Parameters::
+    
     pre_size : int, tuple of int, list of int
         The size of the pre-synaptic group.
     post_size : int, tuple of int, list of int
         The size of the post-synaptic group.
 
-    Returns
-    -------
+    Returns::
+    
     conn : TwoEndConnector
         Return the self.
     """
@@ -201,8 +201,8 @@ def __call__(self, pre_size, post_size):
   def _reset_conn(self, pre_size, post_size):
     """Reset connection attributes.
 
-    Parameters
-    ----------
+    Parameters::
+    
     pre_size : int, tuple of int, list of int
         The size of the pre-synaptic group.
     post_size : int, tuple of int, list of int
@@ -382,9 +382,8 @@ def _make_returns(self, structures, conn_data):
   def require(self, *structures):
     """Require all the connection data needed.
 
-    Examples
-    --------
-
+    Examples::
+    
     >>> import brainpy as bp
     >>> conn = bp.connect.FixedProb(0.1)
     >>> mat = conn.require(10, 20, 'conn_mat')
@@ -514,8 +513,8 @@ def build_conn(self):
     - ``build_coo()``: build a coo sparse connection data.
     - ``build_conn()``: deprecated.
 
-    Returns
-    -------
+    Returns::
+    
     conn: tuple, dict
       A tuple with two elements: connection type (str) and connection data.
       For example: ``return 'csr', (ind, indptr)``
@@ -537,8 +536,8 @@ def build_mat(self):
     - ``build_coo()``: build a coo sparse connection data.
     - ``build_conn()``: deprecated.
 
-    Returns
-    -------
+    Returns::
+    
     conn: Array
       A binary matrix with the shape ``(num_pre, num_post)``.
     """
@@ -548,8 +547,8 @@ def build_mat(self):
   def build_csr(self):
     """Build a csr sparse connection data.
 
-    Returns
-    -------
+    Returns::
+    
     conn: tuple
       A tuple denoting the ``(indices, indptr)``.
     """
@@ -559,8 +558,8 @@ def build_csr(self):
   def build_coo(self):
     """Build a coo sparse connection data.
 
-    Returns
-    -------
+    Returns::
+    
     conn: tuple
       A tuple denoting the ``(pre_ids, post_ids)``.
     """

brainpy/_src/dnn/normalization.py

@@ -52,8 +52,8 @@ class BatchNorm(Layer):
       where :math:`\hat{x}` is the estimated statistic and :math:`x_t` is the
       new observed value.
 
-  Parameters
-  ----------
+  Parameters::
+  
   num_features: int
     ``C`` from an expected input of size ``(..., C)``.
   axis: int, tuple, list
@@ -79,8 +79,8 @@ class BatchNorm(Layer):
     Specifies how devices are grouped. Valid
     only within ``jax.pmap`` collectives.
 
-  References
-  ----------
+  References::
+  
   .. [1] Ioffe, Sergey and Christian Szegedy. “Batch Normalization: Accelerating Deep Network Training by Reducing Internal Covariate Shift.” ArXiv abs/1502.03167 (2015): n. pag.
 
   """
@@ -177,8 +177,8 @@ class BatchNorm1d(BatchNorm):
       where :math:`\hat{x}` is the estimated statistic and :math:`x_t` is the
       new observed value.
 
-  Parameters
-  ----------
+  Parameters::
+  
   num_features: int
     ``C`` from an expected input of size ``(B, L, C)``.
   axis: int, tuple, list
@@ -204,8 +204,8 @@ class BatchNorm1d(BatchNorm):
     Specifies how devices are grouped. Valid
     only within ``jax.pmap`` collectives.
 
-  References
-  ----------
+  References::
+  
   .. [1] Ioffe, Sergey and Christian Szegedy. “Batch Normalization: Accelerating Deep Network Training by Reducing Internal Covariate Shift.” ArXiv abs/1502.03167 (2015): n. pag.
 
   """
@@ -260,8 +260,8 @@ class BatchNorm2d(BatchNorm):
       where :math:`\hat{x}` is the estimated statistic and :math:`x_t` is the
       new observed value.
 
-  Parameters
-  ----------
+  Parameters::
+  
   num_features: int
     ``C`` from an expected input of size ``(B, H, W, C)``.
   axis: int, tuple, list
@@ -287,8 +287,8 @@ class BatchNorm2d(BatchNorm):
     Specifies how devices are grouped. Valid
     only within ``jax.pmap`` collectives.
 
-  References
-  ----------
+  References::
+  
   .. [1] Ioffe, Sergey and Christian Szegedy. “Batch Normalization: Accelerating Deep Network Training by Reducing Internal Covariate Shift.” ArXiv abs/1502.03167 (2015): n. pag.
 
   """
@@ -343,8 +343,8 @@ class BatchNorm3d(BatchNorm):
       where :math:`\hat{x}` is the estimated statistic and :math:`x_t` is the
       new observed value.
 
-  Parameters
-  ----------
+  Parameters::
+  
   num_features: int
     ``C`` from an expected input of size ``(B, H, W, D, C)``.
   axis: int, tuple, list
@@ -370,8 +370,8 @@ class BatchNorm3d(BatchNorm):
     Specifies how devices are grouped. Valid
     only within ``jax.pmap`` collectives.
 
-  References
-  ----------
+  References::
+  
   .. [1] Ioffe, Sergey and Christian Szegedy. “Batch Normalization: Accelerating Deep Network Training by Reducing Internal Covariate Shift.” ArXiv abs/1502.03167 (2015): n. pag.
 
   """
@@ -422,8 +422,8 @@ class LayerNorm(Layer):
   scale and bias to a whole example/whole channel, please use GroupNorm/
   InstanceNorm.
 
-  Parameters
-  ----------
+  Parameters::
+  
   normalized_shape: int, sequence of int
     The input shape from an expected input of size
 
@@ -444,8 +444,8 @@ class LayerNorm(Layer):
     has learnable per-element affine parameters initialized to ones (for weights)
     and zeros (for biases). Default: ``True``.
 
-  Examples
-  --------
+  Examples::
+  
   >>> import brainpy as bp
   >>> import brainpy.math as bm
   >>>
@@ -519,8 +519,8 @@ class GroupNorm(Layer):
   The shape of the data should be (b, d1, d2, ..., c), where `d` denotes the batch
   size and `c` denotes the feature (channel) size.
 
-  Parameters
-  ----------
+  Parameters::
+  
   num_groups: int
     The number of groups. It should be a factor of the number of channels.
   num_channels: int
@@ -536,8 +536,8 @@ class GroupNorm(Layer):
   scale_initializer: Initializer, ArrayType, Callable
     An initializer generating the original scaling matrix
 
-  Examples
-  --------
+  Examples::
+  
   >>> import brainpy as bp
   >>> import brainpy.math as bm
   >>> input = bm.random.randn(20, 10, 10, 6)
@@ -598,8 +598,8 @@ class InstanceNorm(GroupNorm):
   This layer normalizes the data within each feature. It can be regarded as
   a group normalization layer in which `group_size` equals to 1.
 
-  Parameters
-  ----------
+  Parameters::
+  
   num_channels: int
     The number of channels expected in input.
   epsilon: float

brainpy/_src/dyn/synapses/delay_couplings.py

@@ -22,8 +22,8 @@
 class DelayCoupling(Projection):
   """Delay coupling.
 
-  Parameters
-  ----------
+  Parameters::
+  
   delay_var: Variable
     The delay variable.
   var_to_output: Variable, sequence of Variable
@@ -121,9 +121,8 @@ class DiffusiveCoupling(DelayCoupling):
      target_var += coupling
 
 
-  Examples
-  --------
-
+  Examples::
+  
   >>> import brainpy as bp
   >>> from brainpy import rates
   >>> areas = bp.rates.FHN(80, x_ou_sigma=0.01, y_ou_sigma=0.01, name='fhn')
@@ -132,8 +131,8 @@ class DiffusiveCoupling(DelayCoupling):
   >>>                                      initial_delay_data=bp.init.Uniform(0, 0.05))
   >>> net = bp.Network(areas, conn)
 
-  Parameters
-  ----------
+  Parameters::
+  
   coupling_var1: Variable
     The first coupling variable, used for delay.
   coupling_var2: Variable
@@ -227,8 +226,8 @@ class AdditiveCoupling(DelayCoupling):
      coupling = g * delayed_coupling_var
      target_var += coupling
 
-  Parameters
-  ----------
+  Parameters::
+  
   coupling_var: Variable
     The coupling variable, used for delay.
   var_to_output: Variable, sequence of Variable

brainpy/_src/dynold/neurons/fractional_models.py

@@ -60,23 +60,22 @@ class FractionalFHR(FractionalNeuron):
   relatively fixed time of bursting duration. With the increasing of :math:`a`, the
   interburst intervals become shorter and periodic bursting changes to tonic spiking.
 
-  Examples
-  --------
-
+  Examples::
+  
   - [(Mondal, et, al., 2019): Fractional-order FitzHugh-Rinzel bursting neuron model](https://brainpy-examples.readthedocs.io/en/latest/neurons/2019_Fractional_order_FHR_model.html)
 
 
-  Parameters
-  ----------
+  Parameters::
+  
   size: int, sequence of int
     The size of the neuron group.
   alpha: float, tensor
     The fractional order.
   num_memory: int
     The total number of the short memory.
 
-  References
-  ----------
+  References::
+  
   .. [1] Mondal, A., Sharma, S.K., Upadhyay, R.K. *et al.* Firing activities of a fractional-order FitzHugh-Rinzel bursting neuron model and its coupled dynamics. *Sci Rep* **9,** 15721 (2019). https://doi.org/10.1038/s41598-019-52061-4
   """
 
@@ -223,14 +222,13 @@ class FractionalIzhikevich(FractionalNeuron):
   in mV. When the spike reaches its peak value, the membrane voltage :math:`v` and the
   recovery variable :math:`u` are reset according to the above condition.
 
-  Examples
-  --------
-
+  Examples::
+  
   - [(Teka, et. al, 2018): Fractional-order Izhikevich neuron model](https://brainpy-examples.readthedocs.io/en/latest/neurons/2018_Fractional_Izhikevich_model.html)
 
 
-  References
-  ----------
+  References::
+  
   .. [10] Teka, Wondimu W., Ranjit Kumar Upadhyay, and Argha Mondal. "Spiking and
           bursting patterns of fractional-order Izhikevich model." Communications
           in Nonlinear Science and Numerical Simulation 56 (2018): 161-176.

brainpy/_src/dynsys.py

@@ -62,8 +62,8 @@ class DynamicalSystem(bm.BrainPyObject, DelayRegister, SupportInputProj):
      - ``.update_local_delays()``
      - ``.reset_local_delays()``
 
-  Parameters
-  ----------
+  Parameters::
+  
   name : optional, str
     The name of the dynamical system.
   mode: optional, Mode
@@ -431,9 +431,8 @@ def __call__(self, *args, **kwargs):
   def __rrshift__(self, other):
     """Support using right shift operator to call modules.
 
-    Examples
-    --------
-
+    Examples::
+    
     >>> import brainpy as bp
     >>> x = bp.math.random.rand((10, 10))
     >>> l = bp.layers.Activation(bm.tanh)
@@ -515,9 +514,8 @@ class Sequential(DynamicalSystem, SupportAutoDelay, Container):
   On the other hand, the layers in a ``Sequential`` are connected
   in a cascading way.
 
-  Examples
-  --------
-
+  Examples::
+  
   >>> import brainpy as bp
   >>> import brainpy.math as bm
   >>>