From 6672d8fc24b63d5fb74b5f1b2e01441d8623dca4 Mon Sep 17 00:00:00 2001 From: Christopher Dilks Date: Thu, 16 Oct 2025 16:47:05 -0400 Subject: [PATCH 1/2] doc: add documentation for each bank --- docs/mkdocs/generate.sh | 2 +- docs/mkdocs/src/banks.rb | 103 +++++++++++++++++++++++++++++++++------ 2 files changed, 89 insertions(+), 16 deletions(-) diff --git a/docs/mkdocs/generate.sh b/docs/mkdocs/generate.sh index 77110954eb..74cdd27681 100755 --- a/docs/mkdocs/generate.sh +++ b/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 diff --git a/docs/mkdocs/src/banks.rb b/docs/mkdocs/src/banks.rb index 4dafbf674b..480fd5763b 100755 --- a/docs/mkdocs/src/banks.rb +++ b/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}" From f85fa49f4cdde56a0b3664d36a1712d51a2e29ca Mon Sep 17 00:00:00 2001 From: Christopher Dilks Date: Fri, 17 Oct 2025 19:52:10 -0400 Subject: [PATCH 2/2] fix: make it work and look nicer --- docs/mkdocs/docs/index.md | 2 +- docs/mkdocs/mkdocs.yaml | 1 + docs/mkdocs/src/banks.rb | 88 ++++++++++++++++++++++++++++++--------- 3 files changed, 71 insertions(+), 20 deletions(-) diff --git a/docs/mkdocs/docs/index.md b/docs/mkdocs/docs/index.md index bcc06f3adb..ba2d31a68f 100644 --- a/docs/mkdocs/docs/index.md +++ b/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 | --- diff --git a/docs/mkdocs/mkdocs.yaml b/docs/mkdocs/mkdocs.yaml index 17b2f0e054..b6837d28b0 100644 --- a/docs/mkdocs/mkdocs.yaml +++ b/docs/mkdocs/mkdocs.yaml @@ -8,3 +8,4 @@ extra: theme: name: mkdocs user_color_mode_toggle: auto + color_mode: auto diff --git a/docs/mkdocs/src/banks.rb b/docs/mkdocs/src/banks.rb index 480fd5763b..b3742877b5 100755 --- a/docs/mkdocs/src/banks.rb +++ b/docs/mkdocs/src/banks.rb @@ -6,14 +6,49 @@ require 'json' require 'fileutils' +# iguana-created banks have claimed this group ID IguanaGroupNum = 30000 -CommonBanks = [ - 'REC::Particle', - 'RUN::config', - 'REC::Calorimeter', - 'REC::Traj', -] # FIXME: add more, or take inspiration from DST schema +# list of banks to put at the top +# FIXME: adapted from , 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} [INPUT_JSON_DIR] [OUTPUT_DIR] @@ -79,31 +114,46 @@ def bank_md_link(name) 'S' => 'short', } -# output tables +# 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 -## Common Banks - +The banks are listed in tables below, organized by group and item ID. Click on a bank name for its details. """ -CommonBanks.each do |name| - outMain.puts "- #{bank_md_link name}" -end +# common banks table outMain.puts """ -## Full List of Banks +## Common DST Banks -Organized by group and item ID +For convenience, here are commonly used DST banks: -> **NOTE:** Iguana banks, which are defined in the Iguana repository, use group number #{IguanaGroupNum}. """ - -def table_row(out, cols) - out.puts "| #{cols.join ' | '} |" +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| - outMain.puts "\n## Group #{group_id}\n\n" + + # 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|