doc: add documentation for each bank

docs/mkdocs/docs/index.md

@@ -5,7 +5,7 @@
 | | |
 | --- | --- |
 | [**API Documentation**](javadoc/index.html) | Documentation for classes and methods |
-| [**HIPO Bank**](banks.md) | Bank descriptions |
+| [**HIPO Banks**](banks.md) | Bank descriptions |
 | [**Source code**](https://github.com/JeffersonLab/coatjava) | The source code `git` repository |
 
 ---

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/mkdocs.yaml

@@ -8,3 +8,4 @@ extra:
 theme:
   name: mkdocs
   user_color_mode_toggle: auto
+  color_mode: auto

docs/mkdocs/src/banks.rb

@@ -4,19 +4,65 @@
 #
 
 require 'json'
+require 'fileutils'
 
-if ARGV.empty?
+# iguana-created banks have claimed this group ID
+IguanaGroupNum = 30000
+
+# list of banks to put at the top
+# FIXME: adapted from <https://clasweb.jlab.org/wiki/index.php/CLAS12_DSTs>, but maybe we can use schema dirs to automate
+CommonBanks = {
+  'Event banks' => [
+    'RUN::config',
+    'REC::Event',
+  ],
+  'Physics Banks' => [
+    'REC::Particle',
+    'RECFT::Particle',
+    'REC::Calorimeter',
+    'REC::Scintillator',
+    'REC::Cherenkov',
+    'REC::Track',
+    'REC::Traj',
+    'REC::CovMat',
+    'REC::ScintExtras',
+  ],
+  'Special & Tagged Banks' => [
+    'HEL::flip',
+    'RAW::scaler',
+    'RUN::scaler',
+    'HEL::scaler',
+    'RAW::epics',
+    'HEL::online',
+    'HEL::decoder',
+  ],
+  'Simulation Banks' => [
+    'MC::Header',
+    'MC::Event',
+    'MC::Lund',
+    'MC::Particle',
+    'MC::True',
+    'MC::GenMatch',
+    'MC::RecMatch',
+    'MC::User',
+  ],
+}
+
+# usage and args
+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 +89,76 @@
 # 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',
+}
 
-> **NOTE:**  Iguana banks, which are defined in the Iguana repository, use group number 30000.
+# make a table row
+def table_row(out, cols)
+  out.puts "| #{cols.join ' | '} |"
+end
 
+# start output markdown
+FileUtils.mkdir_p OutputDir
+FileUtils.mkdir_p File.join(OutputDir, BanksSubDir)
+outMain = File.open File.join(OutputDir, "banks.md"), 'w'
+outMain.puts """# HIPO Banks
+
+The banks are listed in tables below, organized by group and item ID. Click on a bank name for its details.
 """
 
-def row(cols)
-  puts "| #{cols.join ' | '} |"
+# common banks table
+outMain.puts """
+## Common DST Banks
+
+For convenience, here are commonly used DST banks:
+
+"""
+table_row outMain, ['Group', 'Banks']
+table_row outMain, ['---', '---']
+CommonBanks.each do |group_name, bank_list|
+  table_row outMain, [
+    group_name,
+    bank_list.map{ |bank_name| bank_md_link bank_name }.join(', ')
+  ]
 end
+
+# all other bank tables
 specs_fully_sorted.each do |group_id, spec_list|
-  puts "\n## Group #{group_id}\n\n"
-  row ['Item ID', 'Name', 'Description']
-  row ['---', '---', '---']
+
+  # get list of unique bank-name prefixes
+  uniq_prefixes = spec_list.map do |spec|
+    "`#{spec['name'].gsub /::.*/, ''}`"
+  end.uniq
+
+  outMain.puts "\n## #{uniq_prefixes.join ', '} Banks"
+  outMain.puts "**Group ID:** #{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 +168,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}"