Documentation: Support for including node examples

auxiliary/scripts/auto-generator.py

@@ -357,22 +357,30 @@ def generate_node_library(node_classes):
                 cls_doc_abs_path = os.path.join(root_directory, folder, cls_doc_path)
                 cls_doc_abs_folder = os.path.dirname(cls_doc_abs_path)
                 os.makedirs(cls_doc_abs_folder, exist_ok=True)
+                example_scripts = glob.glob(os.path.join(cls_doc_abs_folder, "*.py"))
+                example_scripts = [os.path.basename(s) for s in example_scripts]
                 with open(cls_doc_abs_path, "w") as fd:
+                    output_markdown_params = ", ".join(("%s=%s" % (param.name, param.default)) \
+                            for param in cls.constructors[0])
+                    output_markdown_params = output_markdown_params.replace("nullptr", "None")
+
                     fd.write(f"title: {cls.name} node documentation\n")
                     fd.write(f"description: {cls.name}: {cls.docs}\n\n")
                     fd.write(
                         f"[Reference library](../../index.md) > [{folder_title}](../index.md) > [{cls.name}](index.md)\n\n")
-                    fd.write(f"# {cls.name}\n\n")
-                    fd.write(f"{cls.docs}\n\n")
 
-                    output_markdown_params = ", ".join(
-                        ("%s=%s" % (param.name, param.default)) for param in cls.constructors[0])
-                    output_markdown_params = output_markdown_params.replace("nullptr", "None")
-                    fd.write(f"Signature:\n")
+                    fd.write(f"# {cls.name}\n\n")
                     fd.write(f"```python\n")
                     fd.write(f"{cls.name}({output_markdown_params})\n")
-                    fd.write(f"```\n")
+                    fd.write(f"```\n\n")
+                    fd.write(f"{cls.docs}\n\n")
 
+                    if len(example_scripts):
+                        fd.write(f"### Examples\n\n")
+                        for example_script in example_scripts:
+                            fd.write(f"```python\n")
+                            fd.write('{%% include-markdown "./%s" comments=false %%}\n' % example_script)
+                            fd.write(f"```\n\n")
 
 def generate_readme(node_classes) -> None:
     """

docs/library/analysis/crosscorrelate/index.md

@@ -5,9 +5,9 @@ description: CrossCorrelate: Outputs the cross-correlation of the input signal w
 
 # CrossCorrelate
 
-Outputs the cross-correlation of the input signal with the given buffer. If hop_size is zero, calculates the cross-correlation every sample.
-
-Signature:
 ```python
 CrossCorrelate(input=None, buffer=None, hop_size=0)
 ```
+
+Outputs the cross-correlation of the input signal with the given buffer. If hop_size is zero, calculates the cross-correlation every sample.
+

docs/library/analysis/onsetdetector/index.md

@@ -5,9 +5,9 @@ description: OnsetDetector: Simple time-domain onset detector. Outputs an impuls
 
 # OnsetDetector
 
-Simple time-domain onset detector. Outputs an impulse when an onset is detected in the input. Maintains short-time and long-time averages. An onset is registered when the short-time average is threshold x the long-time average. min_interval is the minimum interval between onsets, in seconds.
-
-Signature:
 ```python
 OnsetDetector(input=0.0, threshold=2.0, min_interval=0.1)
 ```
+
+Simple time-domain onset detector. Outputs an impulse when an onset is detected in the input. Maintains short-time and long-time averages. An onset is registered when the short-time average is threshold x the long-time average. min_interval is the minimum interval between onsets, in seconds.
+

docs/library/analysis/vampanalysis/index.md

@@ -5,9 +5,9 @@ description: VampAnalysis: Feature extraction using the Vamp plugin toolkit.
 
 # VampAnalysis
 
-Feature extraction using the Vamp plugin toolkit.
-
-Signature:
 ```python
 VampAnalysis(input=0.0, plugin_id="vamp-example-plugins:spectralcentroid:linearcentroid")
 ```
+
+Feature extraction using the Vamp plugin toolkit.
+

docs/library/buffer/beatcutter/index.md

@@ -5,9 +5,9 @@ description: BeatCutter: Cuts a buffer into segment_count segments, and stutters
 
 # BeatCutter
 
-Cuts a buffer into segment_count segments, and stutters/jumps with the given probabilities.
-
-Signature:
 ```python
 BeatCutter(buffer=None, segment_count=8, stutter_probability=0.0, stutter_count=1, jump_probability=0.0, duty_cycle=1.0, rate=1.0, segment_rate=1.0)
 ```
+
+Cuts a buffer into segment_count segments, and stutters/jumps with the given probabilities.
+

docs/library/buffer/bufferlooper/index.md

@@ -5,9 +5,9 @@ description: BufferLooper: Read and write from a buffer concurrently, with contr
 
 # BufferLooper
 
-Read and write from a buffer concurrently, with controllable overdub.
-
-Signature:
 ```python
 BufferLooper(buffer=None, input=0.0, feedback=0.0, loop_playback=false, loop_record=false)
 ```
+
+Read and write from a buffer concurrently, with controllable overdub.
+

docs/library/buffer/bufferplayer/index.md

@@ -5,9 +5,9 @@ description: BufferPlayer: Plays the contents of the given buffer. start_time/en
 
 # BufferPlayer
 
-Plays the contents of the given buffer. start_time/end_time are in seconds. When a clock signal is receives, rewinds to the start_time.
-
-Signature:
 ```python
 BufferPlayer(buffer=None, rate=1.0, loop=0, start_time=None, end_time=None, clock=None)
 ```
+
+Plays the contents of the given buffer. start_time/end_time are in seconds. When a clock signal is receives, rewinds to the start_time.
+

docs/library/buffer/bufferrecorder/index.md

@@ -5,9 +5,9 @@ description: BufferRecorder: Records the input to a buffer. feedback controls ov
 
 # BufferRecorder
 
-Records the input to a buffer. feedback controls overdub.
-
-Signature:
 ```python
 BufferRecorder(buffer=None, input=0.0, feedback=0.0, loop=false)
 ```
+
+Records the input to a buffer. feedback controls overdub.
+

docs/library/buffer/feedbackbufferreader/index.md

@@ -5,9 +5,9 @@ description: FeedbackBufferReader: Counterpart to FeedbackBufferWriter.
 
 # FeedbackBufferReader
 
-Counterpart to FeedbackBufferWriter.
-
-Signature:
 ```python
 FeedbackBufferReader(buffer=None)
 ```
+
+Counterpart to FeedbackBufferWriter.
+

docs/library/buffer/feedbackbufferwriter/index.md

@@ -5,9 +5,9 @@ description: FeedbackBufferWriter: Counterpart to FeedbackBufferReader.
 
 # FeedbackBufferWriter
 
-Counterpart to FeedbackBufferReader.
-
-Signature:
 ```python
 FeedbackBufferWriter(buffer=None, input=0.0, delay_time=0.1)
 ```
+
+Counterpart to FeedbackBufferReader.
+

docs/library/buffer/grainsegments/index.md

@@ -5,9 +5,9 @@ description: GrainSegments: GrainSegments
 
 # GrainSegments
 
-GrainSegments
-
-Signature:
 ```python
 GrainSegments(buffer=None, clock=0, target=0, offsets={}, values={}, durations={})
 ```
+
+GrainSegments
+

docs/library/buffer/granulator/index.md

@@ -5,9 +5,9 @@ description: Granulator: Granulator. Generates a grain from the given buffer eac
 
 # Granulator
 
-Granulator. Generates a grain from the given buffer each time a clock signal is received, with the given duration/rate/pan parameters. The input buffer can be mono or stereo.
-
-Signature:
 ```python
 Granulator(buffer=None, clock=0, pos=0, duration=0.1, pan=0.0, rate=1.0, max_grains=2048)
 ```
+
+Granulator. Generates a grain from the given buffer each time a clock signal is received, with the given duration/rate/pan parameters. The input buffer can be mono or stereo.
+

docs/library/buffer/segmentplayer/index.md

@@ -5,9 +5,9 @@ description: SegmentPlayer: Trigger segments of a buffer at the given onset posi
 
 # SegmentPlayer
 
-Trigger segments of a buffer at the given onset positions.
-
-Signature:
 ```python
 SegmentPlayer(buffer=None, onsets={})
 ```
+
+Trigger segments of a buffer at the given onset positions.
+

docs/library/control/mousedown/index.md

@@ -5,9 +5,9 @@ description: MouseDown: Outputs 1 if the left mouse button is down, 0 otherwise.
 
 # MouseDown
 
-Outputs 1 if the left mouse button is down, 0 otherwise. Currently only supported on macOS.
-
-Signature:
 ```python
 MouseDown(button_index=0)
 ```
+
+Outputs 1 if the left mouse button is down, 0 otherwise. Currently only supported on macOS.
+

docs/library/control/mousex/index.md

@@ -5,9 +5,9 @@ description: MouseX: Outputs the normalised cursor X position, from 0 to 1. Curr
 
 # MouseX
 
-Outputs the normalised cursor X position, from 0 to 1. Currently only supported on macOS.
-
-Signature:
 ```python
 MouseX()
 ```
+
+Outputs the normalised cursor X position, from 0 to 1. Currently only supported on macOS.
+

docs/library/control/mousey/index.md

@@ -5,9 +5,9 @@ description: MouseY: Outputs the normalised cursor Y position, from 0 to 1. Curr
 
 # MouseY
 
-Outputs the normalised cursor Y position, from 0 to 1. Currently only supported on macOS.
-
-Signature:
 ```python
 MouseY()
 ```
+
+Outputs the normalised cursor Y position, from 0 to 1. Currently only supported on macOS.
+

docs/library/envelope/adsrenvelope/index.md

@@ -5,9 +5,9 @@ description: ADSREnvelope: Attack-decay-sustain-release envelope. Sustain portio
 
 # ADSREnvelope
 
-Attack-decay-sustain-release envelope. Sustain portion is held until gate is zero.
-
-Signature:
 ```python
 ADSREnvelope(attack=0.1, decay=0.1, sustain=0.5, release=0.1, gate=0)
 ```
+
+Attack-decay-sustain-release envelope. Sustain portion is held until gate is zero.
+

docs/library/envelope/asrenvelope/index.md

@@ -5,9 +5,9 @@ description: ASREnvelope: Attack-sustain-release envelope.
 
 # ASREnvelope
 
-Attack-sustain-release envelope.
-
-Signature:
 ```python
 ASREnvelope(attack=0.1, sustain=0.5, release=0.1, curve=1.0, clock=None)
 ```
+
+Attack-sustain-release envelope.
+

docs/library/envelope/detectsilence/index.md

@@ -5,9 +5,9 @@ description: DetectSilence: Detects blocks of silence below the threshold value.
 
 # DetectSilence
 
-Detects blocks of silence below the threshold value. Used as an auto-free node to terminate a Patch after processing is complete.
-
-Signature:
 ```python
 DetectSilence(input=None, threshold=0.00001)
 ```
+
+Detects blocks of silence below the threshold value. Used as an auto-free node to terminate a Patch after processing is complete.
+

docs/library/envelope/envelope/index.md

@@ -5,9 +5,9 @@ description: Envelope: Generic envelope constructor, given an array of levels, t
 
 # Envelope
 
-Generic envelope constructor, given an array of levels, times and curves.
-
-Signature:
 ```python
 Envelope(levels=std::vector<NodeRef> ( ), times=std::vector<NodeRef> ( ), curves=std::vector<NodeRef> ( ), clock=None, loop=false)
 ```
+
+Generic envelope constructor, given an array of levels, times and curves.
+

docs/library/envelope/line/index.md

@@ -5,9 +5,9 @@ description: Line: Line segment with the given start/end values and duration. If
 
 # Line
 
-Line segment with the given start/end values and duration. If loop is true, repeats indefinitely. Retriggers on a clock signal.
-
-Signature:
 ```python
 Line(start=0.0, end=1.0, time=1.0, loop=0, clock=None)
 ```
+
+Line segment with the given start/end values and duration. If loop is true, repeats indefinitely. Retriggers on a clock signal.
+

docs/library/envelope/rectangularenvelope/index.md

@@ -5,9 +5,9 @@ description: RectangularEnvelope: Rectangular envelope with the given sustain du
 
 # RectangularEnvelope
 
-Rectangular envelope with the given sustain duration.
-
-Signature:
 ```python
 RectangularEnvelope(sustain_duration=1.0, clock=None)
 ```
+
+Rectangular envelope with the given sustain duration.
+

docs/library/fft/fft/index.md

@@ -5,9 +5,9 @@ description: FFT: Fast Fourier Transform. Takes a time-domain input, and generat
 
 # FFT
 
-Fast Fourier Transform. Takes a time-domain input, and generates a frequency-domain (FFT) output.
-
-Signature:
 ```python
 FFT(input=0.0, fft_size=SIGNALFLOW_DEFAULT_FFT_SIZE, hop_size=SIGNALFLOW_DEFAULT_FFT_HOP_SIZE, window_size=0, do_window=true)
 ```
+
+Fast Fourier Transform. Takes a time-domain input, and generates a frequency-domain (FFT) output.
+

docs/library/fft/fftcontinuousphasevocoder/index.md

@@ -5,9 +5,9 @@ description: FFTContinuousPhaseVocoder: Continuous phase vocoder. Requires an FF
 
 # FFTContinuousPhaseVocoder
 
-Continuous phase vocoder. Requires an FFT* input.
-
-Signature:
 ```python
 FFTContinuousPhaseVocoder(input=None, rate=1.0)
 ```
+
+Continuous phase vocoder. Requires an FFT* input.
+

docs/library/fft/fftconvolve/index.md

@@ -5,9 +5,9 @@ description: FFTConvolve: Frequency-domain convolution, using overlap-add. Usefu
 
 # FFTConvolve
 
-Frequency-domain convolution, using overlap-add. Useful for convolution reverb, with the input buffer containing an impulse response. Requires an FFT* input.
-
-Signature:
 ```python
 FFTConvolve(input=None, buffer=None)
 ```
+
+Frequency-domain convolution, using overlap-add. Useful for convolution reverb, with the input buffer containing an impulse response. Requires an FFT* input.
+

docs/library/fft/fftfindpeaks/index.md

@@ -5,9 +5,9 @@ description: FFTFindPeaks: Find peaks in the FFT magnitude spectrum. Requires an
 
 # FFTFindPeaks
 
-Find peaks in the FFT magnitude spectrum. Requires an FFT* input.
-
-Signature:
 ```python
 FFTFindPeaks(input=0, prominence=1, threshold=0.000001, count=SIGNALFLOW_MAX_CHANNELS, interpolate=true)
 ```
+
+Find peaks in the FFT magnitude spectrum. Requires an FFT* input.
+

docs/library/fft/fftlpf/index.md

@@ -5,9 +5,9 @@ description: FFTLPF: FFT-based brick wall low pass filter. Requires an FFT* inpu
 
 # FFTLPF
 
-FFT-based brick wall low pass filter. Requires an FFT* input.
-
-Signature:
 ```python
 FFTLPF(input=0, frequency=2000)
 ```
+
+FFT-based brick wall low pass filter. Requires an FFT* input.
+

docs/library/fft/fftnoisegate/index.md

@@ -5,9 +5,9 @@ description: FFTNoiseGate: FFT-based noise gate. Requires an FFT* input.
 
 # FFTNoiseGate
 
-FFT-based noise gate. Requires an FFT* input.
-
-Signature:
 ```python
 FFTNoiseGate(input=0, threshold=0.5)
 ```
+
+FFT-based noise gate. Requires an FFT* input.
+