WIP: Resolve docstring errors and transition to MkDocs

.gitignore

@@ -62,4 +62,6 @@ temp
 .venv
 
 .pytest*
-.ruff*
+.ruff*
+
+sphinx-docs

acoustic_toolbox/ambisonics.py

@@ -6,29 +6,26 @@
 
 import numpy as np
 import scipy.special
+from typing import Generator, Tuple
 
 
-def acn(order=1):
+def acn(order: int = 1) -> Generator[Tuple[int, int], None, None]:
     """Spherical harmonic degree `n` and order `m` for ambisonics order `order`.
 
-    :param order: Ambisonics order.
-
-    Yields tuples `(n, m)` where `n` is the degree and `m` the order.
-
     Follows ACN.
 
-    === == == ======
-    ACN n  m  letter
-    === == == ======
-    0   0  0  W
-    --- -- -- ------
-    1   1  -1 Y
-    --- -- -- ------
-    2   1  0  Z
-    --- -- -- ------
-    3   1  +1 X
-    === == == ======
+    | ACN | n | m  | letter |
+    |-----|---|----|--------|
+    | 0   | 0 | 0  | W      |
+    | 1   | 1 | -1 | Y      |
+    | 2   | 1 | 0  | Z      |
+    | 3   | 1 | +1 | X      |
+
+    Args:
+      order: Ambisonics order.
 
+    Yields:
+        Degree `n` and order `m`.
     """
     for n in range(order + 1):
         for m in range(-n, n + 1):
@@ -38,10 +35,13 @@ def acn(order=1):
 def sn3d(m, n):
     """SN3D or Schmidt semi-normalisation
 
-    :param m: order `n`
-    :param n: degree `m`
+    - [http://en.wikipedia.org/wiki/Ambisonic_data_exchange_formats#SN3D](http://en.wikipedia.org/wiki/Ambisonic_data_exchange_formats#SN3D)
 
-    http://en.wikipedia.org/wiki/Ambisonic_data_exchange_formats#SN3D
+    Args:
+      m: order `n`
+      n: degree `m`
+
+    Returns:
 
     """
     m = np.atleast_1d(m)
@@ -60,10 +60,13 @@ def sn3d(m, n):
 def n3d(m, n):
     """N3D or full three-D normalisation
 
-    :param m: order `n`
-    :param n: degree `m`
+    - [http://en.wikipedia.org/wiki/Ambisonic_data_exchange_formats#N3D](http://en.wikipedia.org/wiki/Ambisonic_data_exchange_formats#N3D)
+
+    Args:
+      m: order `n`
+      n: degree `m`
 
-    http://en.wikipedia.org/wiki/Ambisonic_data_exchange_formats#N3D
+    Returns:
 
     """
     n = np.atleast_1d(n)

acoustic_toolbox/standards/iec_61260_1_2014.py

@@ -86,23 +86,26 @@
 def exact_center_frequency(
     x, fraction=1, ref=REFERENCE_FREQUENCY, G=OCTAVE_FREQUENCY_RATIO
 ):
-    """
-    Center frequencies :math:`f_m` for band indices :math:`x`. See equation 2 and 3.
-
-    :param x: Band index :math:`x`.
-    :param ref: Reference center frequency :math:`f_r`.
-    :param fraction: Bandwidth designator :math`b`. For example, for 1/3-octave filter b=3.
-    :param G: Octave frequency ratio :math:`G`.
-
+    """Center frequencies :math:`f_m` for band indices :math:`x`. See equation 2 and 3.
+
+    Args:
+      x: Band index :math:`x`.
+      ref: Reference center frequency :math:`f_r`. (Default value = REFERENCE_FREQUENCY)
+      fraction: Bandwidth designator :math`b`. For example, for 1/3-octave filter b=3. (Default value = 1)
+      G: Octave frequency ratio :math:`G`.
+    
     The center frequencies are given by
-
+    
     .. math:: f_m = f_r G^{x/b}
-
+    
     In case the bandwidth designator :math:`b` is an even number, the center frequencies are given by
-
+    
     .. math:: f_m = f_r G^{(2x+1)/2b}
+
+    See equation 2 and 3 of the standard. (Default value = OCTAVE_FREQUENCY_RATIO)
+
+    Returns:
 
-    See equation 2 and 3 of the standard.
     """
     fraction = np.asarray(fraction)
     uneven = (fraction % 2).astype("bool")
@@ -112,36 +115,40 @@ def exact_center_frequency(
 
 
 def lower_frequency(center, fraction=1, G=OCTAVE_FREQUENCY_RATIO):
-    """
-    Lower band-edge frequencies. See equation 4.
-
-    :param center: Center frequencies :math:`f_m`.
-    :param fraction: Bandwidth designator :math:`b`.
-    :param G: Octave frequency ratio :math:`G`.
+    """Lower band-edge frequencies. See equation 4.
 
+    Args:
+      center: Center frequencies :math:`f_m`.
+      fraction: Bandwidth designator :math:`b`. (Default value = 1)
+      G: Octave frequency ratio :math:`G`.
+
     The lower band-edge frequencies are given by
-
+    
     .. math:: f_1 = f_m G^{-1/2b}
+
+    See equation 4 of the standard. (Default value = OCTAVE_FREQUENCY_RATIO)
 
-    See equation 4 of the standard.
+    Returns:
 
     """
     return center * G ** (-1.0 / (2.0 * fraction))
 
 
 def upper_frequency(center, fraction=1, G=OCTAVE_FREQUENCY_RATIO):
-    """
-    Upper band-edge frequencies. See equation 5.
-
-    :param center: Center frequencies :math:`f_m`.
-    :param fraction: Bandwidth designator :math:`b`.
-    :param G: Octave frequency ratio :math:`G`.
+    """Upper band-edge frequencies. See equation 5.
 
+    Args:
+      center: Center frequencies :math:`f_m`.
+      fraction: Bandwidth designator :math:`b`. (Default value = 1)
+      G: Octave frequency ratio :math:`G`.
+
     The upper band-edge frequencies are given by
-
+    
     .. math:: f_2 = f_m G^{+1/2b}
+
+    See equation 5 of the standard. (Default value = OCTAVE_FREQUENCY_RATIO)
 
-    See equation 5 of the standard.
+    Returns:
 
     """
     return center * G ** (+1.0 / (2.0 * fraction))
@@ -150,18 +157,25 @@ def upper_frequency(center, fraction=1, G=OCTAVE_FREQUENCY_RATIO):
 def index_of_frequency(
     frequency, fraction=1, ref=REFERENCE_FREQUENCY, G=OCTAVE_FREQUENCY_RATIO
 ):
-    """Determine the band index `x` from a given frequency.
-
-    :param frequency: Frequencies :math:`f`.
-    :param fraction: Bandwidth designator :math:`b`.
-    :param ref: Reference frequency.
-    :param G: Octave frequency ratio :math:`G`.
-
+    """Determine the band index $x$ from a given frequency.
+
+    Args:
+      frequency: Frequencies $f$.
+      fraction: Bandwidth designator $b$. (Default value = 1)
+      ref: Reference frequency. (Default value = REFERENCE_FREQUENCY)
+      G: Octave frequency ratio $G$.
+
     The index of the center frequency is given by
 
-    .. math:: x = round{b \\frac{\log{f/f_{ref} }}{\log{G} }}
+    $$
+    x = round{b \\frac{\\log{f/f_{ref} }}{\\log{G} }}
+    $$
+
+    Note:
+        This equation is not part of the standard. 
+        However, it follows from [`exact_center_frequency`](acoustic_toolbox.standards.iec_61260_1_2014.exact_center_frequency).
 
-    .. note:: This equation is not part of the standard. However, it follows from :func:`exact_center_frequency`.
+    Returns:
 
     """
     fraction = np.asarray(fraction)
@@ -178,11 +192,24 @@ def index_of_frequency(
 def _nominal_center_frequency(center, fraction):
     """Nominal frequency according to standard.
 
-    :param center: Exact mid-frequency to be rounded.
-    :param fraction: Bandwidth designator or fraction.
+    Args:
+      center: Exact mid-frequency to be rounded.
+      fraction: Bandwidth designator or fraction.
+
+    Returns:
+
     """
 
     def _roundn(x, n):
+        """
+
+        Args:
+          x: 
+          n: 
+
+        Returns:
+
+        """
         return round(x, -int(np.floor(np.sign(x) * np.log10(abs(x)))) + n)
 
     b = fraction

docs/ambisonics.md

@@ -0,0 +1,5 @@
+::: acoustic_toolbox.ambisonics
+    options:
+        show_root_heading: false
+        show_source: true
+        show_docstring_yields: true

docs/index.md

@@ -0,0 +1,65 @@
+# Acoustic Toolbox
+
+Welcome to the documentation of the acoustic-toolbox module!
+
+## Examples
+
+<div class="grid cards" markdown>
+
+- [Signal Class](signal_class.md)
+- [Directivity](directivity.md)
+
+</div>
+
+## API Reference
+
+This section contains a description of all classes and functions.
+
+### Signal class
+
+<div class="grid cards" markdown>
+
+- [Signal](signal.md)
+
+</div>
+
+### Modules
+
+<div class="grid cards" markdown>
+
+- [Ambisonics](ambisonics.md)
+- [Atmosphere](atmosphere.md)
+- [Bands](bands.md)
+- [Building](building.md)
+- [Cepstrum](cepstrum.md)
+- [Criterion](criterion.md)
+- [Decibel](decibel.md)
+- [Generator](generator.md)
+- [Descriptors](descriptors.md)
+- [Doppler](doppler.md)
+- [Imaging](imaging.md)
+- [Octave](octave.md)
+- [Power](power.md)
+- [Reflection](reflection.md)
+- [Room](room.md)
+- [Utils](utils.md)
+- [Weighting](weighting.md)
+- [Quantity](quantity.md)
+
+</div>
+
+### Standards
+
+The `acoustic_toolbox.standards` module consists of modules where all code and values are according to the respective standard.
+
+<div class="grid cards" markdown>
+
+- [Standards](standards.md)
+
+</div>
+
+## Indices and tables
+
+- [Genindex](genindex-broken.md)
+- [Modindex](modindex-broken.md)
+- [Search](search-broken.md)

docs/javascripts/katex.js

@@ -0,0 +1,10 @@
+document$.subscribe(({ body }) => { 
+    renderMathInElement(body, {
+      delimiters: [
+        { left: "$$",  right: "$$",  display: true },
+        { left: "$",   right: "$",   display: false },
+        { left: "\\(", right: "\\)", display: false },
+        { left: "\\[", right: "\\]", display: true }
+      ],
+    })
+  })

docs/javascripts/readthedocs.js

@@ -0,0 +1,32 @@
+document.addEventListener("DOMContentLoaded", function(event) {
+    // Trigger Read the Docs' search addon instead of Material MkDocs default
+    document.querySelector(".md-search__input").addEventListener("focus", (e) => {
+            const event = new CustomEvent("readthedocs-search-show");
+            document.dispatchEvent(event);
+        });
+    });
+
+// Use CustomEvent to generate the version selector
+document.addEventListener(
+    "readthedocs-addons-data-ready",
+    function (event) {
+    const config = event.detail.data();
+    const versioning = `
+<div class="md-version">
+<button class="md-version__current" aria-label="Select version">
+${config.versions.current.slug}
+</button>
+
+<ul class="md-version__list">
+${ config.versions.active.map(
+(version) => `
+<li class="md-version__item">
+<a href="${ version.urls.documentation }" class="md-version__link">
+    ${ version.slug }
+</a>
+        </li>`).join("\n")}
+</ul>
+</div>`;
+
+document.querySelector(".md-header__topic").insertAdjacentHTML("beforeend", versioning);
+});