doc: add documentation for each bank

Author: c-dilks

docs/mkdocs/generate.sh

@@ -25,7 +25,7 @@ top_dir=$src_dir/../..
 # generate build files
 cp $src_dir/mkdocs.yaml $build_dir/
 cp -r $src_dir/docs $build_dir/
-$src_dir/src/banks.rb $top_dir/etc/bankdefs/hipo4 > $build_dir/docs/banks.md
+$src_dir/src/banks.rb $top_dir/etc/bankdefs/hipo4 $build_dir/docs
 tree $build_dir
 
 # build

docs/mkdocs/src/banks.rb

@@ -4,19 +4,30 @@
 #
 
 require 'json'
+require 'fileutils'
 
-if ARGV.empty?
+IguanaGroupNum = 30000
+CommonBanks = [
+  'REC::Particle',
+  'RUN::config',
+  'REC::Calorimeter',
+  'REC::Traj',
+] # FIXME: add more, or take inspiration from DST schema
+
+unless ARGV.size == 2
   puts """
-  USAGE: #{$0} [DIRECTORY]
+  USAGE: #{$0} [INPUT_JSON_DIR] [OUTPUT_DIR]
 
-  Dumps the bank names and ID information for all JSON files in [DIRECTORY]
+  Dumps the bank names and ID information for all JSON files in [INPUT_JSON_DIR]
+  Output files will appear in [OUTPUT_DIR]
   """
   exit 2
 end
-SpecDir = ARGV[0]
+InputJsonDir = ARGV[0]
+OutputDir    = ARGV[1]
 
 # parse the JSON files
-specs = Dir.glob(File.join SpecDir, '*.json').map do |spec_file_name|
+specs = Dir.glob(File.join InputJsonDir, '*.json').map do |spec_file_name|
   JSON.parse File.read(spec_file_name)
 end.flatten
 
@@ -43,26 +54,61 @@
 # then sort each group's item IDs
 specs_fully_sorted = Hash.new
 specs_grouped_sorted.each do |group_id, spec_list|
+  raise "do not define a bank with group ID #{IguanaGroupNum}, since that is reserved for Iguana" if group_id==IguanaGroupNum
   specs_fully_sorted[group_id] = spec_list.sort do |spec_a, spec_b|
     spec_a['item'].to_i <=> spec_b['item'].to_i
   end
 end
 
-# dump a table
-puts """# Bank Group and Item IDs
+# functions to give bank details markdown file name and link
+BanksSubDir = 'banks'
+def bank_md_name(name)
+  File.join(BanksSubDir, name.gsub(/::/,'_')) + '.md'
+end
+def bank_md_link(name)
+  "[`#{name}`](#{bank_md_name name})"
+end
+
+# data type hash
+TypeHash = {
+  'B' => 'byte',
+  'D' => 'double',
+  'F' => 'float',
+  'I' => 'int',
+  'L' => 'long',
+  'S' => 'short',
+}
+
+# output tables
+FileUtils.mkdir_p OutputDir
+outMain = File.open File.join(OutputDir, "banks.md"), 'w'
+outMain.puts """# HIPO Banks
+
+## Common Banks
+
+"""
+CommonBanks.each do |name|
+  outMain.puts "- #{bank_md_link name}"
+end
+
+outMain.puts """
+## Full List of Banks
 
-> **NOTE:**  Iguana banks, which are defined in the Iguana repository, use group number 30000.
+Organized by group and item ID
 
+> **NOTE:**  Iguana banks, which are defined in the Iguana repository, use group number #{IguanaGroupNum}.
 """
 
-def row(cols)
-  puts "| #{cols.join ' | '} |"
+def table_row(out, cols)
+  out.puts "| #{cols.join ' | '} |"
 end
 specs_fully_sorted.each do |group_id, spec_list|
-  puts "\n## Group #{group_id}\n\n"
-  row ['Item ID', 'Name', 'Description']
-  row ['---', '---', '---']
+  outMain.puts "\n## Group #{group_id}\n\n"
+  table_row outMain, ['Item ID', 'Name', 'Description']
+  table_row outMain, ['---', '---', '---']
   spec_list.each do |spec|
+
+    # clean up description
     desc = spec['info'].split.map do |word|
       if word.include? '::'
         "`#{word}`"
@@ -72,10 +118,37 @@ def row(cols)
         word
       end
     end.join(' ')
-    row [
+
+    # output main table row
+    table_row outMain, [
       spec['item'],
-      '`' + spec['name'] + '`',
+      bank_md_link(spec['name']),
       desc,
     ]
+
+    # generate detailed table
+    outBank = File.open File.join(OutputDir, bank_md_name(spec['name'])), 'w'
+    outBank.puts """# `#{spec['name']}` Bank Details
+
+#{desc}
+
+[Return to main tables](../banks.md)
+
+"""
+    table_row outBank, ['Item Name', 'Type', 'Description']
+    table_row outBank, ['---', '---', '---']
+    spec['entries'].each do |entry|
+      datatype = TypeHash[entry['type']]
+      raise "unknown datatype '#{datatype}'" if datatype.nil?
+      table_row outBank, [
+        "`#{entry['name']}`",
+        "`#{datatype}`",
+        entry['info']
+      ]
+    end
+    outBank.close
   end
 end
+outMain.close
+
+puts "OUTPUT FILES WRITTEN TO #{OutputDir}"