Feature/spec refactor (#50)

* hadamard

* householder

* version bump

* api tweak

* bump version

* tweaks

* version bump

* typo

* v bump

* pull spec out and generate traits using Claude

* wip doc gen

* generate docs

* starting docs

* wip docs

* shiki

* more docs

* wip docs

* more docs

* a bit half-assed, but some docs

* more docs

* sidebar

* basic docs

* version bump

* redirect

* vercel different sqlite adapter

* fmt

* wip docs

* mobile layout

* anchor fix

* layout fix

* bare bones meta

* mobile tweaks

---------

Co-authored-by: Luke <luke.weston@cyberus-technology.de>

Author: lukeweston1234

.gitignore

@@ -5,7 +5,8 @@ target/
 /samples
 example.png
 example.wav
-*.png
+/*.png
+/scripts/**/*.png
 *.wav
 crates/legato-core/samples
 /result

crates/Cargo.lock

@@ -1,12 +1,18 @@
 [package]
 name = "legato"
 description = "Legato is a WIP audiograph and DSL for quickly developing audio applications"
-version = "0.0.25"
+version = "0.0.28"
 edition = "2024"
 repository="https://github.com/legato-dsp/legato"
 license = "AGPL-3.0"
 
+[features]
+docs = ["dep:serde", "dep:serde_json"]
+
 [dependencies]
+serde = { version = "1", features = ["derive"], optional = true }
+serde_json = { version = "1", optional = true }
+
 assert_no_alloc = "1.1.2"
 portable-atomic = { version = "1.11.1", features = ["float"] }
 arc-swap = "1.7.1"
@@ -27,6 +33,11 @@ rtrb = "0.3.3"
 [dev-dependencies]
 criterion = { version = "0.5", features = ["html_reports"] }
 
+[[bin]]
+name = "export-docs"
+path = "src/bin/export_docs.rs"
+required-features = ["docs"]
+
 [[bench]]
 name = "nodes"
 harness = false

crates/Cargo.toml

@@ -4,6 +4,7 @@ use legato::{
     builder::{LegatoBuilder, Unconfigured},
     config::Config,
     interface::AudioInterface,
+    msg::ParamPayload,
     ports::PortBuilder,
 };
 

crates/examples/delay.rs

@@ -79,10 +79,10 @@ fn main() {
 
     // Spawn prod consumer pair
 
-    let (producer, consumer) = rtrb::RingBuffer::new(4096 * 4); // 4 frames of headroom
-
     let ports = PortBuilder::default().audio_out(2).build();
 
+    let (producer, consumer) = rtrb::RingBuffer::new(4096 * 4); // 4 frames of headroom
+
     let (app, _) = LegatoBuilder::<Unconfigured>::new(config, ports)
         .register_audio_input("one", consumer, 1, config.block_size)
         .build_dsl(&graph);

crates/examples/external.rs

@@ -0,0 +1,4 @@
+fn main() {
+    #[cfg(feature = "docs")]
+    println!("{}", legato::docs::export_nodes_json());
+}

crates/src/bin/export_docs.rs

@@ -141,6 +141,7 @@ impl LegatoBuilder<Unconfigured> {
         let control_registry = control_registry_factory();
         let midi_registry = midi_registry_factory();
 
+        // Default namespaces
         namespaces.insert("audio".into(), audio_registry);
         namespaces.insert("control".into(), control_registry);
         namespaces.insert("midi".into(), midi_registry);

crates/src/builder.rs

@@ -0,0 +1,79 @@
+use crate::{
+    nodes::{
+        audio::{
+            adsr::Adsr,
+            allpass::Allpass,
+            delay::{DelayRead, DelayWrite},
+            external::ExternalInput,
+            hadamard::HadamardMixer,
+            householder::HouseholderMixer,
+            mixer::{MonoFanOut, TrackMixer},
+            onepole::OnePole,
+            ops::{AddDef, DivDef, GainDef, MultDef, SubDef},
+            sampler::Sampler,
+            sine::Sine,
+            svf::Svf,
+            sweep::Sweep,
+        },
+        control::{
+            map::Map,
+            phasor::{ClockDef, Phasor},
+            sequencer::StepSequencer,
+            signal::Signal,
+        },
+        midi::voice::{PolyVoice, Voice},
+    },
+    spec::{NodeDefinition, NodeDoc},
+};
+
+pub fn audio_node_docs() -> Vec<NodeDoc> {
+    vec![
+        Sine::doc(),
+        Sampler::doc(),
+        DelayWrite::doc(),
+        DelayRead::doc(),
+        TrackMixer::doc(),
+        MultDef::doc(),
+        AddDef::doc(),
+        SubDef::doc(),
+        DivDef::doc(),
+        GainDef::doc(),
+        Adsr::doc(),
+        Svf::doc(),
+        MonoFanOut::doc(),
+        Sweep::doc(),
+        OnePole::doc(),
+        Allpass::doc(),
+        HadamardMixer::doc(),
+        HouseholderMixer::doc(),
+        ExternalInput::doc(),
+    ]
+}
+
+pub fn control_node_docs() -> Vec<NodeDoc> {
+    vec![
+        Signal::doc(),
+        Map::doc(),
+        Phasor::doc(),
+        ClockDef::doc(),
+        StepSequencer::doc(),
+    ]
+}
+
+pub fn midi_node_docs() -> Vec<NodeDoc> {
+    vec![Voice::doc(), PolyVoice::doc()]
+}
+
+/// Returns documentation for all built-in nodes across audio, control, and MIDI namespaces.
+pub fn all_node_docs() -> Vec<NodeDoc> {
+    let mut docs = audio_node_docs();
+    docs.extend(control_node_docs());
+    docs.extend(midi_node_docs());
+    docs
+}
+
+/// Serialises all built-in node documentation to JSON
+#[cfg(feature = "docs")]
+pub fn export_nodes_json() -> String {
+    serde_json::to_string_pretty(&all_node_docs()).expect("NodeDoc serialisation failed")
+}

crates/src/docs.rs

@@ -41,6 +41,8 @@ pub mod simd;
 pub mod spec;
 pub mod window;
 
+#[cfg(feature = "docs")]
+pub mod docs;
 pub mod nodes;
 
 #[derive(Debug, PartialEq, Clone)]

crates/src/lib.rs

@@ -166,3 +166,30 @@ impl Node for Adsr {
         &self.ports
     }
 }
+
+use crate::{
+    builder::{ResourceBuilderView, ValidationError},
+    dsl::ir::DSLParams,
+    node::DynNode,
+    spec::NodeDefinition,
+};
+
+impl NodeDefinition for Adsr {
+    const NAME: &'static str = "adsr";
+    const DESCRIPTION: &'static str = "Attack-decay-sustain-release envelope generator";
+    const REQUIRED_PARAMS: &'static [&'static str] =
+        &["attack", "decay", "sustain", "release", "chans"];
+    const OPTIONAL_PARAMS: &'static [&'static str] = &[];
+
+    fn create(
+        _rb: &mut ResourceBuilderView,
+        p: &DSLParams,
+    ) -> Result<Box<dyn DynNode>, ValidationError> {
+        let attack = p.get_f32("attack").expect("Must provide attack to ADSR");
+        let decay = p.get_f32("decay").expect("Must provide decay to ADSR");
+        let sustain = p.get_f32("sustain").expect("Must provide sustain to ADSR");
+        let release = p.get_f32("release").expect("Must provide release to ADSR");
+        let chans = p.get_usize("chans").expect("Must provide chans to ADSR");
+        Ok(Box::new(Self::new(chans, attack, decay, sustain, release)))
+    }
+}