From e003c5fd8a09c3f8d8abe9f0f02a7296f0715c47 Mon Sep 17 00:00:00 2001
From: Sebastian Holzapfel <me@sebholzapfel.com>
Date: Wed, 2 Oct 2024 20:18:28 +0200
Subject: [PATCH] doc2

---
 gateware/docs/dsp.rst              | 68 ++++++++++++++++++++++++++----
 gateware/src/tiliqua/delay_line.py | 24 +++++------
 gateware/src/tiliqua/dsp.py        | 16 ++++---
 3 files changed, 82 insertions(+), 26 deletions(-)

diff --git a/gateware/docs/dsp.rst b/gateware/docs/dsp.rst
index dc99410c..632ef112 100644
--- a/gateware/docs/dsp.rst
+++ b/gateware/docs/dsp.rst
@@ -8,21 +8,73 @@ TODO short overview of the DSP library philosophy.
 
 TODO link to Amaranth documentation on streams.
 
-Stream helpers
---------------
+Delay Lines
+-----------
 
-.. autoclass:: tiliqua.dsp.Split
+.. autoclass:: tiliqua.delay_line.DelayLine
 
-.. autoclass:: tiliqua.dsp.Merge
+Filters
+-------
+
+.. autoclass:: tiliqua.dsp.SVF
+.. autoclass:: tiliqua.dsp.FIR
+.. autoclass:: tiliqua.dsp.Boxcar
+
+
+Oscillators
+-----------
+
+.. autoclass:: tiliqua.dsp.SawNCO
+
+Effects
+-------
+
+.. autoclass:: tiliqua.dsp.WaveShaper
+.. autoclass:: tiliqua.dsp.PitchShift
 
 VCAs
 ----
 
 .. autoclass:: tiliqua.dsp.VCA
-
 .. autoclass:: tiliqua.dsp.GainVCA
 
-Delay Lines
------------
+Mixing
+------
 
-.. autoclass:: tiliqua.delay_line.DelayLine
+.. autoclass:: tiliqua.dsp.MatrixMix
+
+Resampling
+----------
+
+.. autoclass:: tiliqua.dsp.Resample
+
+One-shot
+--------
+
+.. autoclass:: tiliqua.dsp.Trigger
+.. autoclass:: tiliqua.dsp.Ramp
+
+Stream utilities
+----------------
+
+Splitting / merging streams
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. autoclass:: tiliqua.dsp.Split
+.. autoclass:: tiliqua.dsp.Merge
+
+Connecting and remapping streams
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. autofunction:: tiliqua.dsp.connect_remap
+.. autofunction:: tiliqua.dsp.channel_remap
+
+Connecting streams in feedback loops
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. autoclass:: tiliqua.dsp.KickFeedback
+.. autofunction:: tiliqua.dsp.connect_feedback_kick
+
+Other utilities
+---------------
+
+.. autofunction:: tiliqua.dsp.named_submodules
diff --git a/gateware/src/tiliqua/delay_line.py b/gateware/src/tiliqua/delay_line.py
index fdf9f5df..a7b91c82 100644
--- a/gateware/src/tiliqua/delay_line.py
+++ b/gateware/src/tiliqua/delay_line.py
@@ -135,18 +135,6 @@ class DelayLine(wiring.Component):
         Only present for PSRAM-backed delay lines. This is the Wishbone bus
         interface for connecting to external PSRAM.
 
-    Constructor Arguments
-    ---------------------
-    max_delay : int
-        The maximum delay in samples.
-    psram_backed : bool, optional
-        If True, the delay line is backed by PSRAM. Default is False.
-    addr_width_o : int, optional
-        The address width (required for PSRAM-backed delay lines)
-    base : int, optional
-        The memory slice base address (required PSRAM-backed delay lines).
-    write_triggers_read : bool, optional
-        If True, writing to the delay line triggers a read. Default is True.
 
     """
 
@@ -155,6 +143,18 @@ class DelayLine(wiring.Component):
 
     def __init__(self, max_delay, psram_backed=False, addr_width_o=None, base=None,
                  write_triggers_read=True):
+        """
+        max_delay : int
+            The maximum delay in samples.
+        psram_backed : bool, optional
+            If True, the delay line is backed by PSRAM.
+        addr_width_o : int, optional
+            The address width (required for PSRAM-backed delay lines)
+        base : int, optional
+            The memory slice base address (required PSRAM-backed delay lines).
+        write_triggers_read : bool, optional
+            If True, writing to the delay line triggers a read.
+        """
 
         if psram_backed:
             assert base is not None
diff --git a/gateware/src/tiliqua/dsp.py b/gateware/src/tiliqua/dsp.py
index 1cba4eb3..f1c0f3be 100644
--- a/gateware/src/tiliqua/dsp.py
+++ b/gateware/src/tiliqua/dsp.py
@@ -119,12 +119,12 @@ def connect_remap(m, stream_o, stream_i, mapping):
     map it to a different stream with a StructLayout payload, and the underlying
     bit-representation of both layouts do not match, I can remap using:
 
-    ```
-    dsp.connect_remap(m, vca_merge2a.o, vca0.i, lambda o, i : [
-        i.payload.x   .eq(o.payload[0]),
-        i.payload.gain.eq(o.payload[1] << 2)
-    ])
-    ```
+    .. code-block:: python
+
+        dsp.connect_remap(m, vca_merge2a.o, vca0.i, lambda o, i : [
+            i.payload.x   .eq(o.payload[0]),
+            i.payload.gain.eq(o.payload[1] << 2)
+        ])
 
     This is a bit of a hack. TODO perhaps implement this as a StreamConverter
     such that we can still use wiring.connect?.
@@ -1012,6 +1012,8 @@ def named_submodules(m_submodules, elaboratables, override_name=None):
     """
     Normally, using constructs like:
 
+    .. code-block:: python
+
         m.submodules += delaylines
 
     You get generated code with names like U$14 ... as Amaranth's
@@ -1019,6 +1021,8 @@ def named_submodules(m_submodules, elaboratables, override_name=None):
 
     Instead, you can do:
 
+    .. code-block:: python
+
         named_submodules(m.submodules, delaylines)
 
     And this helper will give each instance a name.