Server - begin DSL and synth/fx documentation templating

Author: ethancrawford

app/server/ruby/bin/qt-doc2.rb

@@ -0,0 +1,82 @@
+#!/usr/bin/env ruby
+#--
+# This file is part of Sonic Pi: http://sonic-pi.net
+# Full project source: https://github.com/samaaron/sonic-pi
+# License: https://github.com/samaaron/sonic-pi/blob/main/LICENSE.md
+#
+# Copyright 2013, 2014, 2015, 2016 by Sam Aaron (http://sam.aaron.name).
+# All rights reserved.
+#
+# Permission is granted for use, copying, modification, and
+# distribution of modified versions of this work as long as this
+# notice is included.
+#++
+
+require 'cgi'
+require 'optparse'
+require 'fileutils'
+
+require_relative "../core.rb"
+require_relative "../lib/sonicpi/lang/support/docsystem"
+require_relative "../lib/sonicpi/synths/synthinfo"
+require_relative "../lib/sonicpi/util"
+require_relative "../lib/sonicpi/runtime"
+require_relative "../lib/sonicpi/lang/core"
+require_relative "../lib/sonicpi/lang/sound"
+require_relative "../lib/sonicpi/lang/minecraftpi"
+require_relative "../lib/sonicpi/lang/midi"
+require 'active_support/inflector'
+require 'erb'
+require 'gettext'
+require "gettext/tools/xgettext"
+
+
+class QtDocs
+  include SonicPi::Lang::Support::DocSystem
+  include SonicPi::Util
+  include GetText
+
+  def run
+    # _generate_lang_docs
+    _generate_synth_docs
+  end
+
+  def t_(arg)
+    "<%= _(\"#{arg}\") %>"
+  end
+
+  private
+  def _generate_lang_docs
+    _generate_docs(@@docs, lang_template_path, lang_toml_path)
+  end
+
+  def _generate_synth_docs
+    collection = SonicPi::Synths::SynthInfo.get_all.select do |k, v|
+      v.is_a?(SonicPi::Synths::SynthInfo) && v.user_facing?
+    end
+    _generate_docs(
+      collection,
+      synth_and_fx_template_path,
+      synth_toml_path,
+      SonicPi::Synths::SynthInfo
+    )
+  end
+
+  def _generate_docs(collection, template_path, output_path, klass = nil)
+    original_template = File.read(template_path)
+    collection.to_a.take(2).map do |key, item|
+      template = ERB.new(original_template).result(binding)
+      interpolated_path = "#{interpolated_template_path}/#{key}.toml.erb"
+      File.open(interpolated_path, 'w') do |f|
+        f.write template
+      end
+
+      GetText::Tools::XGetText.run(
+        interpolated_path,
+        "-o ../../../../../../etc/doc/generated/toml/synths/test.pot"
+      )
+    end
+  end
+end
+
+QtDocs.new.run

etc/doc/templates/interpolated/dull_bell.toml.erb

@@ -0,0 +1,221 @@
+<%= _("# This is a data file that contains information describing the text that is
+# displayed on pages in the Synths section of Sonic Pi's help panel.
+
+# A unique identifier for this synth or fx, the word that is typed in the code
+# to use it.
+# (For example: :pretty_bell).
+") %>
+[:dull_bell]
+
+<%= _("# A word or short phrase that is used as a label for the synth or fx.
+# (For example: Pretty Bell).
+") %>
+name = "<%= _("Dull Bell") %>"
+
+<%= _("# A basic code example of how to use the synth or fx.") %>
+usage = '''
+use_synth :dull_bell
+'''
+
+<%= _("# The detailed description of the synth or fx.") %>
+doc = '''
+<%= _("A simple dull discordant bell sound.") %>
+'''
+
+<%= _("# The label describing the version of Sonic Pi in which this synth or fx first
+# appeared.
+") %>
+[:dull_bell.introduced]
+label = "<%= _("Introduced in v2.0") %>"
+
+<%= _("# The options are the opts of this synth or fx.
+# In the documentation, we currently display two table of opts:
+# - one listing the name of each opt and its default value for easy reference
+# - a second, more detailed table labelled 'Options', containing:
+#   - the name of each opt
+#   - a detailed description of it
+#   - its default value
+#   - (if the opt has constraints (limits or range of permitted values, etc):
+#     the constraints of the opt
+#   - a label describing whether this opt can be modulated (altered) while the
+#     synth or fx is running
+#   - (if the opt is slidable): a label indicating that the opt is slidable
+") %>
+[:dull_bell.options]
+label = "<%= _("Options") %>"
+
+[[:dull_bell.options.list]]
+name = "note:"
+doc = "<%= _("Note to play. Either a MIDI number or a symbol representing a note. For example: `30`, `52`, `:C`, `:C2`, `:Eb4`, or `:Ds3`") %>"
+default_value = "52"
+
+constraints = '''
+<%= _("Must be zero or greater") %>
+'''
+
+modulatable = '''
+<%= _("May be changed whilst playing") %>
+'''
+
+[[:dull_bell.options.list]]
+name = "amp:"
+doc = "<%= _("The amplitude of the sound. Typically a value between 0 and 1. Higher amplitudes may be used, but won't make the sound louder, they will just reduce the quality of all the sounds currently being played (due to compression.)") %>"
+default_value = "1"
+
+constraints = '''
+<%= _("Must be zero or greater") %>
+'''
+
+modulatable = '''
+<%= _("May be changed whilst playing") %>
+'''
+
+[[:dull_bell.options.list]]
+name = "pan:"
+doc = "<%= _("Position of sound in stereo. With headphones on, this means how much of the sound is in the left ear, and how much is in the right ear. With a value of -1, the sound is completely in the left ear, a value of 0 puts the sound equally in both ears and a value of 1 puts the sound in the right ear. Values in between -1 and 1 move the sound accordingly.") %>"
+default_value = "0"
+
+constraints = '''
+<%= _("Must be a value between -1 and 1 inclusively") %>
+'''
+
+modulatable = '''
+<%= _("May be changed whilst playing") %>
+'''
+
+[[:dull_bell.options.list]]
+name = "attack:"
+doc = "<%= _("Amount of time (in beats) for sound to reach full amplitude (attack_level). A short attack (i.e. 0.01) makes the initial part of the sound very percussive like a sharp tap. A longer attack (i.e 1) fades the sound in gently. Full length of sound is attack + decay + sustain + release.") %>"
+default_value = "0"
+
+constraints = '''
+<%= _("Must be zero or greater") %>
+'''
+
+modulatable = '''
+<%= _("Can not be changed once set") %>
+'''
+
+[[:dull_bell.options.list]]
+name = "decay:"
+doc = "<%= _("Amount of time (in beats) for the sound to move from full amplitude (attack_level) to the sustain amplitude (sustain_level).") %>"
+default_value = "0"
+
+constraints = '''
+<%= _("Must be zero or greater") %>
+'''
+
+modulatable = '''
+<%= _("Can not be changed once set") %>
+'''
+
+[[:dull_bell.options.list]]
+name = "sustain:"
+doc = "<%= _("Amount of time (in beats) for sound to remain at sustain level amplitude. Longer sustain values result in longer sounds. Full length of sound is attack + decay + sustain + release.") %>"
+default_value = "0"
+
+constraints = '''
+<%= _("Must be zero or greater") %>
+'''
+
+modulatable = '''
+<%= _("Can not be changed once set") %>
+'''
+
+[[:dull_bell.options.list]]
+name = "release:"
+doc = "<%= _("Amount of time (in beats) for sound to move from sustain level amplitude to silent. A short release (i.e. 0.01) makes the final part of the sound very percussive (potentially resulting in a click). A longer release (i.e 1) fades the sound out gently. Full length of sound is attack + decay + sustain + release.") %>"
+default_value = "1"
+
+constraints = '''
+<%= _("Must be zero or greater") %>
+'''
+
+modulatable = '''
+<%= _("Can not be changed once set") %>
+'''
+
+[[:dull_bell.options.list]]
+name = "attack_level:"
+doc = "<%= _("Amplitude level reached after attack phase and immediately before decay phase") %>"
+default_value = "1"
+
+constraints = '''
+<%= _("Must be zero or greater") %>
+'''
+
+modulatable = '''
+<%= _("Can not be changed once set") %>
+'''
+
+[[:dull_bell.options.list]]
+name = "decay_level:"
+doc = "<%= _("Amplitude level reached after decay phase and immediately before sustain phase. Defaults to sustain_level unless explicitly set") %>"
+default_value = "sustain_level"
+
+constraints = '''
+<%= _("Must be zero or greater") %>
+'''
+
+modulatable = '''
+<%= _("Can not be changed once set") %>
+'''
+
+[[:dull_bell.options.list]]
+name = "sustain_level:"
+doc = "<%= _("Amplitude level reached after decay phase and immediately before release phase.") %>"
+default_value = "1"
+
+constraints = '''
+<%= _("Must be zero or greater") %>
+'''
+
+modulatable = '''
+<%= _("Can not be changed once set") %>
+'''
+
+[[:dull_bell.options.list]]
+name = "env_curve:"
+doc = "<%= _("Select the shape of the curve between levels in the envelope. 1=linear, 2=exponential, 3=sine, 4=welch, 6=squared, 7=cubed") %>"
+default_value = "2"
+
+constraints = '''
+<%= _("Must be one of the following values: [1, 2, 3, 4, 6, 7]") %>
+'''
+
+modulatable = '''
+<%= _("Can not be changed once set") %>
+'''
+
+
+[sliding]
+slide_label = "Slide Options"
+slide_description = '''
+Any parameter that is slidable has three additional options named _slide,
+slide_curve, and _slide_shape.  For example, 'amp' is slidable, so you can also
+set amp_slide, amp_slide_curve, and amp_slide_shape with the following effects:
+'''
+
+
+[[sliding.slide_opts]]
+name = "_slide"
+default = "0"
+doc = '''
+Amount of time (in beats) for the parameter value to change. A long parameter_slide value means that the parameter takes a long time to slide from the previous value to the new value. A parameter_slide of 0 means that the parameter instantly changes to the new value.
+'''
+
+[[sliding.slide_opts]]
+name = "_slide_shape"
+default = "5"
+doc = '''
+Shape of curve. 0: step, 1: linear, 3: sine, 4: welch, 5: custom (use *_slide_curve: opt e.g. amp_slide_curve:), 6: squared, 7: cubed. 
+'''
+
+[[sliding.slide_opts]]
+name = "_slide_curve"
+default = "0"
+doc = '''
+Shape of the slide curve (only honoured if slide shape is 5). 0 means linear and positive and negative numbers curve the segment up and down respectively.
+'''
+
+