Add more documentation to signal module

sci-rs/src/signal/filter/design/kaiser.rs

@@ -26,6 +26,8 @@ use num_traits::{real::Real, MulAdd, Pow, ToPrimitive};
 /// use sci_rs::signal::filter::design::kaiser_beta;
 /// assert_eq!(6.20426, kaiser_beta(65.));
 /// ```
+/// # See Also
+/// [kaiser_atten], [kaiserord]
 pub fn kaiser_beta<F>(a: F) -> F
 where
     F: Real + MulAdd<Output = F> + Pow<F, Output = F>,

sci-rs/src/signal/filter/mod.rs

@@ -13,7 +13,9 @@ pub use kalmanfilt::kalman::kalman_filter;
 ///
 pub use gaussfilt as gaussian_filter;
 
-/// Digital IIR/FIR filter design
+/// Digital IIR/FIR filter design  
+/// Functions located in the [`Filter design` section of
+/// `scipy.signal`](https://docs.scipy.org/doc/scipy/reference/signal.html#filter-design).
 pub mod design;
 
 mod ext;

sci-rs/src/signal/mod.rs

@@ -1,23 +1,32 @@
-/// Digital Filtering
+/// Digital Filtering  
+/// Contains functions from [Filtering section of
+/// `scipy.signal`](https://docs.scipy.org/doc/scipy/reference/signal.html#filtering).
 pub mod filter;
 
-/// Signal Generation
+/// Signal Generation  
+/// Contains functions from the [Waveforms section of
+/// `scipy.signal`](<https://docs.scipy.org/doc/scipy/reference/signal.html#waveforms>).
 pub mod wave;
 
-/// Convolution
+/// Convolution  
+/// Contains functions from the [Convolution section of
+/// `scipy.signal`](<https://docs.scipy.org/doc/scipy/reference/signal.html#convolution>).
 #[cfg(feature = "std")]
 pub mod convolve;
 
 /// Window functions  
 /// This contains all window functions in the
-/// [scipy.signal.windows](https://docs.scipy.org/doc/scipy/reference/signal.windows.html#module-scipy.signal.windows)
+/// [`scipy.signal.windows`](https://docs.scipy.org/doc/scipy/reference/signal.windows.html#module-scipy.signal.windows)
 /// namespace.  
 /// The convenience function
 /// [`get_windows`](https://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.get_window.html#scipy.signal.get_window)
 /// in the [scipy.signal](https://docs.scipy.org/doc/scipy/reference/signal.html#window-functions)
 /// namespace is located here.
 pub mod windows;
 
-/// Signal Resampling
+/// Signal Resampling  
+/// This contains only the
+/// [`resample`](https://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.resample.html#scipy.signal.resample)
+/// function from `scipy.signal`.
 #[cfg(feature = "std")]
 pub mod resample;

sci-rs/src/signal/wave/mod.rs

@@ -1,7 +1,6 @@
 use nalgebra::RealField;
 use ndarray::{Array, ArrayBase, Data, Dimension, RawData};
 
-/// """
 /// Return a periodic square-wave waveform.
 ///
 /// The square wave has a period ``2*pi``, has value +1 from 0 to
@@ -14,31 +13,34 @@ use ndarray::{Array, ArrayBase, Data, Dimension, RawData};
 ///
 /// Parameters
 /// ----------
-/// t : array_like
+/// * `t` : array_like  
 ///     The input time array.
-/// duty : array_like, optional
-///     Duty cycle.  Default is 0.5 (50% duty cycle).
-///     If an array, causes wave shape to change over time, and must be the
-///     same length as t.
+/// * `duty` : array_like  
+///     Duty cycle.  
+///     not implemented: If an array, causes wave shape to change over time, and must be the same
+///     length as t.
 ///
 /// Returns
 /// -------
-/// y : ndarray
+/// `y` : ndarray  
 ///     Output array containing the square waveform.
 ///
 /// Examples
 /// --------
 /// A 5 Hz waveform sampled at 500 Hz for 1 second:
 ///
+/// ```custom,{class=language-python}
 /// >>> import numpy as np
 /// >>> from scipy import signal
 /// >>> import matplotlib.pyplot as plt
 /// >>> t = np.linspace(0, 1, 500, endpoint=False)
 /// >>> plt.plot(t, signal.square(2 * np.pi * 5 * t))
 /// >>> plt.ylim(-2, 2)
+/// ```
 ///
 /// A pulse-width modulated sine wave:
 ///
+/// ```custom,{class=language-python}
 /// >>> plt.figure()
 /// >>> sig = np.sin(2 * np.pi * t)
 /// >>> pwm = signal.square(2 * np.pi * 30 * t, duty=(sig + 1)/2)
@@ -47,8 +49,7 @@ use ndarray::{Array, ArrayBase, Data, Dimension, RawData};
 /// >>> plt.subplot(2, 1, 2)
 /// >>> plt.plot(t, pwm)
 /// >>> plt.ylim(-1.5, 1.5)
-///
-/// """
+/// ```
 pub fn square<F, S, D>(t: &ArrayBase<S, D>, duty: F) -> Array<F, D>
 where
     F: RealField,