Server - update doc generating script & templates

Both the generating of the documentation TOML files and the Phoenix app's build
process are now hooked into the pre-build process. The TOML templates have also
been updated.

Author: ethancrawford

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"
 

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"
 
@@ -90,3 +92,8 @@ mix release
 
 cp src/tau.app.src ebin/tau.app
 cd "${SCRIPT_DIR}"
+cd "${SCRIPT_DIR}/../etc/docs"
+mix deps.get
+cd "${SCRIPT_DIR}/../etc/docs/assets"
+yarn install
+cd "${SCRIPT_DIR}"

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

@@ -49,6 +49,7 @@ def t_(arg)
 
   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|
@@ -58,25 +59,31 @@ def generate_docs
         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(interpolated_template_path) unless File.exist?(interpolated_template_path)
+    cwd = Dir.pwd
+    Dir.chdir(generated_path)
     GetText::Tools::XGetText.run(
       *interpolated_file_paths,
-      "-o ../../../../../../etc/doc/generated/toml/synths/test.pot"
+      '-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
@@ -90,6 +97,7 @@ def generate_toml_files
   end
 
   def sync_to_documentation_app
+    puts 'Syncing the TOML files to the documentation web app...'
     FileUtils.cp_r(doc_toml_path, documentation_app_priv_path, remove_destination: true)
   end
 
@@ -137,7 +145,6 @@ def lang
       output_path: lang_toml_path
     }
   end
-
 end
 
 QtDocs.new.run

app/win-prebuild.bat

@@ -47,6 +47,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
 

etc/doc/templates/lang.toml.erb

@@ -2,13 +2,12 @@
 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
 )
 %>
-<%
-  summary = item[:summary]
-  summary[0] = summary[0].capitalize
-%>
 [<%= item[:name] %>]
 
 <%=
@@ -17,6 +16,10 @@ t_(<<~TEXT.chomp
 # a summary phrase: 'Create chord').
 TEXT
 )
+-%>
+<%
+summary = item[:summary]
+summary[0] = summary[0].capitalize
 %>
 summary = "<%= t_(summary) %>"
 
@@ -81,4 +84,7 @@ label_plural = "<%= t_('Examples') %>"
 <% item[:examples].each_with_index do |e, index| %>
 [[<%= item[:name] %>.examples.list]]
 label = "<%= t_("Example #{index + 1}") %>"
+example = '''
+<%= e %>
+'''
 <% end %>

etc/doc/templates/samples.toml.erb

@@ -0,0 +1,79 @@
+<%=
+t_(<<~TEXT.chomp
+   # This is a data file that contains information describing the text that is
+   # displayed on pages in the Samples section of Sonic Pi's help panel.
+
+   # A unique identifier for a group of samples, so that samples are grouped
+   # into 'categories'.
+   # (For example: ambi).
+   TEXT
+)
+%>
+[<%= key %>]
+
+<%=
+t_(<<~TEXT.chomp
+   # A word or short phrase that is used as a label for the sample group.
+   # (For example: Ambient Sounds).
+   TEXT
+)
+%>
+name = "<%= t_(item[:desc]) %>"
+
+<%= t_('# Basic code examples of how to use the samples in the group.') %>
+usage = '''
+<%= item[:samples].map do |s|
+    "sample :#{s}"
+ end.join("\n")
+%>
+'''
+
+<%=
+t_(<<~TEXT.chomp
+# The options are the opts of the sample function.
+# In the documentation, we currently display two tables 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 a specific range of permitted
+#     values, etc)): the constraints of the opt
+#   - a label describing whether this opt can be modulated (altered) while the
+#     sample is running
+#   - (if the opt is slidable): a label indicating that the opt is slidable
+TEXT
+)
+%>
+[<%= key %>.options]
+label = "<%= t_('Options') %>"
+<% data_object.arg_info.each do |name, attributes| %>
+[[<%= key %>.options.list]]
+name = "<%= name %>:"
+doc = '''
+<%= t_(attributes[:doc] || 'write me') %>
+'''
+default_value = "<%= attributes[:default] %>"
+<% unless attributes[:constraints].empty? -%>
+constraints = '''
+<%= t_(attributes[:constraints].join(', ').capitalize) %>
+'''
+<% end -%>
+modulatable = '''
+<%=
+t_(
+    if attributes[:modulatable]
+    'May be changed whilst playing'
+    else
+    'Can not be changed once set'
+    end
+)
+%>
+'''
+<% end -%>
+
+<%=
+if data_object.arg_info.any? { |name, arg| arg[:slidable] }
+    ERB.new(File.read(slides_template_path), nil, '-', eoutvar: '_slide01').result(binding)
+end
+%>

etc/doc/templates/slides.toml.erb

@@ -7,8 +7,7 @@ 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:
 TEXT
-)
-%>
+)%>
 '''
 <%
 slide_opts = {

etc/doc/templates/synth_and_fx.toml.erb

@@ -3,9 +3,8 @@ t_(<<~TEXT.chomp
 # 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).
+# A unique identifier for this synth or fx.
+# (For example: pretty_bell).
 TEXT
 )
 %>
@@ -74,11 +73,11 @@ label = "<%= t_('Options') %>"
 name = "<%= name %>:"
 doc = "<%= t_(attributes[:doc] || 'write me') %>"
 default_value = "<%= attributes[:default] %>"
-<% unless attributes[:constraints].empty? %>
+<% unless attributes[:constraints].empty? -%>
 constraints = '''
 <%= t_(attributes[:constraints].join(', ').capitalize) %>
 '''
-<% end %>
+<% end -%>
 modulatable = '''
 <%=
 t_(