Documentation rebuild

app/linux-prebuild.sh

@@ -39,6 +39,8 @@ echo "Translating tutorial..."
 ruby "${SCRIPT_DIR}"/server/ruby/bin/i18n-tool.rb -t
 
 echo "Generating docs for the Qt GUI..."
+ruby "${SCRIPT_DIR}"/server/ruby/bin/qt-doc2.rb
+# TODO: remove the below lines once the new documentation system is integrated into the GUI
 cp "${SCRIPT_DIR}"/gui/qt/utils/ruby_help.tmpl "${SCRIPT_DIR}"/gui/qt/utils/ruby_help.h
 ruby "${SCRIPT_DIR}"/server/ruby/bin/qt-doc.rb -o "${SCRIPT_DIR}"/gui/qt/utils/ruby_help.h
 
@@ -52,4 +54,6 @@ MIX_ENV="${MIX_ENV:-prod}" mix deps.get
 MIX_ENV="${MIX_ENV:-prod}" mix release --overwrite
 
 cp src/tau.app.src ebin/tau.app
+cd "${SCRIPT_DIR}/../etc/docs"
+mix setup
 cd "${SCRIPT_DIR}"

app/mac-prebuild.sh

@@ -75,6 +75,8 @@ echo "Translating tutorial..."
 "$RUBY" "${SCRIPT_DIR}"/server/ruby/bin/i18n-tool.rb -t
 
 echo "Generating docs for the Qt GUI..."
+$RUBY "${SCRIPT_DIR}"/server/ruby/bin/qt-doc2.rb
+# TODO: remove the below lines once the new documentation system is integrated into the GUI
 cp "${SCRIPT_DIR}"/gui/qt/utils/ruby_help.tmpl "${SCRIPT_DIR}"/gui/qt/utils/ruby_help.h
 "$RUBY" "${SCRIPT_DIR}"/server/ruby/bin/qt-doc.rb -o "${SCRIPT_DIR}"/gui/qt/utils/ruby_help.h
 
@@ -89,4 +91,6 @@ MIX_ENV="${MIX_ENV:-prod}" mix deps.get
 MIX_ENV="${MIX_ENV:-prod}" mix release --overwrite
 
 cp src/tau.app.src ebin/tau.app
+cd "${SCRIPT_DIR}/../etc/docs"
+mix setup
 cd "${SCRIPT_DIR}"

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

@@ -0,0 +1,152 @@
+#!/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_relative '../paths'
+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_docs
+    sync_to_documentation_app
+  end
+
+  def t_(arg)
+    # this didn't work on docstrings containing "blah"
+    arg = arg.tr('"', "\"") if arg.is_a?(String)
+    "<%= _(\"#{arg}\") %>"
+  end
+
+  private
+  def generate_docs
+    puts 'Rendering the interpolated TOML erb files...'
+    interpolated_file_paths = [synths, fx, samples, lang].each_with_object([]) do |collection, paths|
+      original_template = File.read(collection[:template_path])
+      collection[:items].to_a.take(2).each do |key, item|
+        # this really needs a more elegant way of reading arg/slide data from the object for
+        # all types (synths/fx/samples)
+        data_object = collection[:data_object] || item
+        key = key.to_s[3..-1] if collection[:klass] == SonicPi::Synths::FXInfo
+        interpolated_file_path = "#{collection[:interpolated_path]}/#{key}.toml.erb"
+        template = ERB.new(original_template, nil, '-').result(binding)
+        FileUtils.mkdir_p(collection[:interpolated_path]) unless File.exist?(collection[:interpolated_path])
+        File.open(interpolated_file_path, 'w') do |f|
+          f.write template
+        end
+        paths << interpolated_file_path
+      end
+    end
+    generate_pot_file(interpolated_file_paths)
+    generate_toml_files
+  end
+
+  def generate_pot_file(interpolated_file_paths)
+    puts 'Extracting the translatable text into pot file...'
+    FileUtils.mkdir_p(::SonicPi::Paths.interpolated_template_path) unless File.exist?(::SonicPi::Paths.interpolated_template_path)
+    cwd = Dir.pwd
+    FileUtils.mkdir_p(::SonicPi::Paths.generated_path) unless File.exist?(::SonicPi::Paths.generated_path)
+    Dir.chdir(::SonicPi::Paths.generated_path)
+    GetText::Tools::XGetText.run(
+      *interpolated_file_paths,
+      '-otest.pot'
+    )
+    Dir.chdir(cwd)
+  end
+
+  def generate_toml_files
+    puts 'Rendering the final TOML output files...'
+    [synths, fx, samples, lang].each do |collection|
+      collection[:items].to_a.take(2).each do |key, item|
+        key = key.to_s[3..-1] if collection[:klass] == SonicPi::Synths::FXInfo
+        interpolated_file = File.read("#{collection[:interpolated_path]}/#{key}.toml.erb")
+        output = ERB.new(interpolated_file, nil, '-').result(binding)
+        FileUtils.mkdir_p(collection[:output_path]) unless File.exist?(collection[:output_path])
+        File.open("#{collection[:output_path]}/#{key}.toml", 'w') do |f|
+          f.write output
+        end
+      end
+    end
+  end
+
+  def sync_to_documentation_app
+    puts 'Syncing the TOML files to the documentation web app...'
+    FileUtils.cp_r(::SonicPi::Paths.doc_toml_path, ::SonicPi::Paths.documentation_app_priv_path, remove_destination: true)
+  end
+
+  def synths
+    items = SonicPi::Synths::SynthInfo.get_all.select do |k, v|
+      v.is_a?(SonicPi::Synths::SynthInfo) && v.user_facing?
+    end
+    {
+      items: items,
+      template_path: ::SonicPi::Paths.synth_and_fx_template_path,
+      interpolated_path: ::SonicPi::Paths.synths_interpolated_path,
+      output_path: ::SonicPi::Paths.synths_toml_path,
+      klass: SonicPi::Synths::SynthInfo
+    }
+  end
+
+  def fx
+    items = SonicPi::Synths::SynthInfo.get_all.select do |k, v|
+      v.is_a?(SonicPi::Synths::FXInfo) && v.user_facing? && !(k.to_s.include? 'replace_')
+    end
+    {
+      items: items,
+      template_path: ::SonicPi::Paths.synth_and_fx_template_path,
+      interpolated_path: ::SonicPi::Paths.fx_interpolated_path,
+      output_path: ::SonicPi::Paths.fx_toml_path,
+      klass: SonicPi::Synths::FXInfo
+    }
+  end
+
+  def samples
+    {
+      items: SonicPi::Synths::SynthInfo.grouped_samples,
+      template_path: ::SonicPi::Paths.samples_template_path,
+      interpolated_path: ::SonicPi::Paths.samples_interpolated_path,
+      output_path: ::SonicPi::Paths.samples_toml_path,
+      data_object: SonicPi::Synths::StereoPlayer.new
+    }
+  end
+
+  def lang
+    {
+      items: @@docs,
+      template_path: ::SonicPi::Paths.lang_template_path,
+      interpolated_path: ::SonicPi::Paths.lang_interpolated_path,
+      output_path: ::SonicPi::Paths.lang_toml_path
+    }
+  end
+end
+
+QtDocs.new.run

app/server/ruby/lib/sonicpi/synths/synthinfo.rb

@@ -3819,7 +3819,7 @@ def specific_arg_info
 
           :pitch_dis =>
           {
-            :doc => "Pitch dispersion - how much random variation in pitch to add. Using a low value like 0.001 can help to \"soften up\" the metallic sounds, especially on drum loops. To be really technical, pitch_dispersion is the maximum random deviation of the pitch from the pitch ratio (which is set by the pitch param)",
+            :doc => "Pitch dispersion - how much random variation in pitch to add. Using a low value like 0.001 can help to 'soften up' the metallic sounds, especially on drum loops. To be really technical, pitch_dispersion is the maximum random deviation of the pitch from the pitch ratio (which is set by the pitch param)",
             :validations => [v_greater_than_oet(:pitch_dis, 0)],
             :modulatable => true
           },

app/server/ruby/paths.rb

@@ -61,6 +61,10 @@ def self.doc_path
       File.absolute_path("#{etc_path}/doc")
     end
 
+    def self.generated_path
+      File.absolute_path("#{doc_path}/generated")
+    end
+
     def self.cheatsheets_path
       File.absolute_path("#{doc_path}/cheatsheets")
     end
@@ -69,6 +73,70 @@ def self.tutorial_path
       File.absolute_path("#{doc_path}/tutorial")
     end
 
+    def self.doc_templates_path
+      File.absolute_path("#{doc_path}/templates")
+    end
+
+    def self.lang_template_path
+      File.absolute_path("#{doc_templates_path}/lang.toml.erb")
+    end
+
+    def self.synth_and_fx_template_path
+      File.absolute_path("#{doc_templates_path}/synth_and_fx.toml.erb")
+    end
+
+    def self.slides_template_path
+      File.absolute_path("#{doc_templates_path}/slides.toml.erb")
+    end
+
+    def self.samples_template_path
+      File.absolute_path("#{doc_templates_path}/samples.toml.erb")
+    end
+
+    def self.interpolated_template_path
+      File.absolute_path("#{generated_path}/interpolated_templates")
+    end
+
+    def self.lang_interpolated_path
+      File.absolute_path("#{interpolated_template_path}/lang")
+    end
+
+    def self.synths_interpolated_path
+      File.absolute_path("#{interpolated_template_path}/synths")
+    end
+
+    def self.fx_interpolated_path
+      File.absolute_path("#{interpolated_template_path}/fx")
+    end
+
+    def self.samples_interpolated_path
+      File.absolute_path("#{interpolated_template_path}/samples")
+    end
+
+    def self.doc_toml_path
+      File.absolute_path("#{doc_path}/generated/toml")
+    end
+
+    def self.lang_toml_path
+      File.absolute_path("#{doc_toml_path}/lang")
+    end
+
+    def self.synths_toml_path
+      File.absolute_path("#{doc_toml_path}/synths")
+    end
+
+    def self.fx_toml_path
+      File.absolute_path("#{doc_toml_path}/fx")
+    end
+
+    def self.samples_toml_path
+      File.absolute_path("#{doc_toml_path}/samples")
+    end
+
+    def self.documentation_app_priv_path
+      File.absolute_path("#{etc_path}/docs/priv/")
+    end
+
     def self.tmp_path
       File.absolute_path("#{root_path}/tmp")
     end

app/win-prebuild.bat

@@ -46,6 +46,8 @@ xcopy /Y /I /R /E external\build\sp_link-prefix\src\sp_link-build\Release\*.dll
 server\native\ruby\bin\ruby server/ruby/bin/i18n-tool.rb -t
 
 @echo Generating docs for the Qt GUI...
+server\native\ruby\bin\ruby server/ruby/bin/qt-doc2.rb
+REM TODO: remove the below lines once the new documentation system is integrated into the GUI
 copy /Y gui\qt\utils\ruby_help.tmpl gui\qt\utils\ruby_help.h
 server\native\ruby\bin\ruby server/ruby/bin/qt-doc.rb -o gui\qt\utils/ruby_help.h
 
@@ -62,4 +64,6 @@ cmd /c mix release --overwrite
 
 cd %~dp0\server\beam\tau
 copy /Y src\tau.app.src .\ebin\tau.app
+cd %~dp0\..\etc\docs
+cmd /c mix setup
 cd %~dp0

etc/doc/templates/lang.toml.erb

@@ -0,0 +1,90 @@
+<%=
+t_(<<~TEXT.chomp
+# This is a data file that contains information describing the text that is
+# displayed on pages in the Lang section of Sonic Pi's help panel.
+
+# A unique identifier for this function.
+# (For example: chord).
+TEXT
+)
+%>
+[<%= item[:name] %>]
+
+<%=
+t_(<<~TEXT.chomp
+# A short phrase describing this Sonic Pi function. (Eg the 'chord' function has
+# a summary phrase: 'Create chord').
+TEXT
+)
+-%>
+<%
+summary = item[:summary]
+summary[0] = summary[0].capitalize
+%>
+summary = "<%= t_(summary) %>"
+
+<%=
+t_(<<~TEXT.chomp
+# Args are the required parameters for the function. Each arg has two documented
+# properties:
+# - the arg's name
+# - the arg's type (number, integer, symbol, ...).
+TEXT
+)
+-%>
+<% item[:args].each do |name, type| %>
+[[<%= item[:name] %>.args]]
+name = "<%= name %>"
+type = "<%= t_(type) %>"
+<% end %>
+<%= t_('# The detailed description of this function.') %>
+doc = '''
+<%= t_(item[:doc]) %>
+'''
+
+<%=
+t_(<<~TEXT.chomp
+# The label describing the version of Sonic Pi in which this function first
+# appeared.
+TEXT
+)
+%>
+[<%= item[:name] %>.introduced]
+label = "<%= t_("Introduced in #{item[:introduced].to_s}") %>"
+<% if item[:opts] && !item[:opts].empty? %>
+
+<%=
+t_(<<~TEXT.chomp
+# The options are the optional parameters of this function.
+# Each option has two documented properties:
+# - the option's name
+# - the option's description doc.
+TEXT
+)
+%>
+[<%= item[:name] %>.options]
+label = "<%= t_('Options') %>"
+<% item[:opts].each do |name, doc| %>
+[[<%= item[:name] %>.options.list]]
+name = "<%= name.to_s %>"
+doc = "<%= t_(doc) %>"
+<% end %>
+<% end %>
+<%=
+t_(<<~TEXT.chomp
+# Each function may have one or more examples. If it has any, they are listed
+# under an overall 'Example' or 'Examples' label (heading), and each example has
+# a numbered sub-heading, such as 'Example 1'.
+TEXT
+)
+%>
+[<%= item[:name] %>.examples]
+label = "<%= t_('Example') %>"
+label_plural = "<%= t_('Examples') %>"
+<% item[:examples].each_with_index do |e, index| %>
+[[<%= item[:name] %>.examples.list]]
+label = "<%= t_("Example #{index + 1}") %>"
+example = '''
+<%= e %>
+'''
+<% end %>