From bf7e3bbad691a7c7ed2175554f24abd5bd531f65 Mon Sep 17 00:00:00 2001 From: Paul Gierz Date: Thu, 23 May 2024 09:44:06 +0200 Subject: [PATCH 1/9] docs(version.rb): yard via ChatGPT --- lib/version.rb | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/lib/version.rb b/lib/version.rb index f6d9b25..4d4b394 100644 --- a/lib/version.rb +++ b/lib/version.rb @@ -1,3 +1,7 @@ module Seamore - VERSION = '2.1.1' # version number according to semantic versioning (SemVer) paradigm + # The current version of the Seamore library following the semantic + # versioning (SemVer) paradigm. + # + # @return [String] the current version of the Seamore library. + VERSION = '2.1.1' end From 2873e9e1696c58ac5650128f4c933083b9c4d10d Mon Sep 17 00:00:00 2001 From: Paul Gierz Date: Thu, 23 May 2024 09:56:43 +0200 Subject: [PATCH 2/9] docs(steps_chain.rb): yard via ChatGPT --- lib/steps_chain.rb | 50 ++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 44 insertions(+), 6 deletions(-) diff --git a/lib/steps_chain.rb b/lib/steps_chain.rb index e2e5ca1..930394e 100644 --- a/lib/steps_chain.rb +++ b/lib/steps_chain.rb @@ -1,9 +1,20 @@ module CMORizer + # The StepsChain class manages the sequence of processing steps for converting + # FESOM variable data to CMOR-compliant format. It initializes the necessary steps, + # handles the execution of these steps, and manages the metadata required for the process. class StepsChain attr_reader :input_variable_name, :input_frequency_name - - # fesom_variable_description: "fesom name"_"available frequency" - # cmor_variable_description: "variable_id"_"CMIP table_id" + + # Initializes a StepsChain instance. + # + # This constructor sets up the processing chain for converting FESOM variable data to CMOR-compliant format. + # It parses the provided descriptions for FESOM and CMOR variables, initializes the steps from a given block + # or default step classes, and prepares the chain for execution. + # + # @param default_step_classes [Array] Default classes for processing steps if no specific steps are provided. + # @param fesom_variable_description [String] Description of the FESOM variable in the format "variable_name_frequency". + # @param cmor_variable_description [String] Description of the CMOR variable in the format "variable_id_table_id". + # @param block [Proc] An optional block to customize the processing steps. def initialize(default_step_classes, fesom_variable_description, cmor_variable_description, &block) @input_variable_name, @input_frequency_name = fesom_variable_description.split('_') @cmor_variable_id, @cmor_table_id = cmor_variable_description.split('_') @@ -16,12 +27,21 @@ def initialize(default_step_classes, fesom_variable_description, cmor_variable_d @step_classes = default_step_classes if @step_classes.empty? end - + # Returns a string representation of the steps chain. + # + # @return [String] A string in the format "input_variable_input_frequency ==> cmor_variable_id_cmor_table_id". def to_s "#{@input_variable_name}_#{@input_frequency_name} ==> #{@cmor_variable_id}_#{@cmor_table_id}" end - + + # Executes the processing steps on the provided FESOM files. + # + # @param fesom_files [Array] List of FESOM files to process. + # @param experiment [Experiment] The experiment metadata. + # @param data_request [DataRequest] The data request metadata. + # @param grid_description_file [String] The grid description file path. + # @param version_date [String] The version date for the output files. def execute(fesom_files, experiment, data_request, grid_description_file, version_date) return if @step_classes.empty? @@ -95,6 +115,17 @@ def execute(fesom_files, experiment, data_request, grid_description_file, versio end + # Creates global attributes for the output files. + # + # @param experiment [Experiment] The experiment metadata. + # @param first_file_year [Integer] The year of the first file. + # @param last_file_year [Integer] The year of the last file. + # @param variable_id [String] The variable ID. + # @param frequency [String] The frequency of the data. + # @param table_id [String] The CMIP table ID. + # @param realms [Array] The realms associated with the variable. + # @param version_date [String] The version date for the output files. + # @return [GlobalAttributes] The global attributes for the output files. private def create_global_attributes(experiment:, first_file_year:, last_file_year:, variable_id:, frequency:, table_id:, realms:, version_date:) builder = GlobalAttributesBuilder.new builder.set_experiment_info(id: experiment.experiment_id, @@ -120,12 +151,19 @@ def execute(fesom_files, experiment, data_request, grid_description_file, versio end + # Adds a processing step to the steps chain. + # + # @param sym [Symbol] The symbol representing the step class. private def add_step(sym) cls = CMORizer::Step.const_get sym @step_classes << cls end - + # Handles undefined methods to add steps to the chain. + # + # @param method_sym [Symbol] The name of the undefined method. + # @param args [Array] The arguments passed to the undefined method. + # @param block [Proc] An optional block passed to the undefined method. def method_missing(method_sym, *args, &block) return super unless @eval_mode # we assume every unknown method designates a sub-task From db2d3f0a23ac475a735d44642864d692b806f034 Mon Sep 17 00:00:00 2001 From: Paul Gierz Date: Mon, 27 May 2024 09:28:33 +0200 Subject: [PATCH 3/9] docs(fesom_possible_var.rb): docstrings and notes, still some clarifications needed --- lib/fesom_possible_var.rb | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/lib/fesom_possible_var.rb b/lib/fesom_possible_var.rb index 13f0aeb..eb08dea 100644 --- a/lib/fesom_possible_var.rb +++ b/lib/fesom_possible_var.rb @@ -12,6 +12,23 @@ def initialize(variable_id, unit, description, time_method) end + # Generates a collection of FesomPossibleVar objects based upon a FORTRAN code snippet + # + # Maps each line of the argument [String] code via a regex based upon the initialization of + # this class, using attributes , , and . + # + # Special handling of the variable "tso", which uses TimeMethods::POINT instead of the + # default TimeMethods::Mean + # + # TODO(PG -- Reverse Engineering): I still need to find out of the regex **needs** the parameters + # or if instead it is used to **figure out what values they should have for initialization**. + # + # NOTE(PG -- Reverse Engineering): This looks like the Ruby equivalent of a Python `classmethod` + # and seems to implement an alternative way of constructing objects of this class. + # + # @param code [String] `FORTRAN` code to pare + # @param sort [Boolean] Whether or not to return the variables sorted (alphabetically?) by `variable_id`. + # @return [Array] An array of FesomPossibleVar objects def self.create_from_fortran_code(code, sort: true) vars = code.split("\n").map do |init_line| /.+?, ['"](?[^,]+?)['"], ['"](?.+?)['"], ['"](?[^,]+?)['"]\) *.*/ =~ init_line @@ -30,7 +47,8 @@ def self.create_from_fortran_code(code, sort: true) end end - + # Helper method to nicely print out this FesomPossibleVar. + # @return [String] def to_s "#{@variable_id}: '#{@unit}' #{@time_method} '#{@description}'" end From 10e8bc09cfc60acb364e20a4be1e4fa302e0a853 Mon Sep 17 00:00:00 2001 From: Paul Gierz Date: Fri, 7 Jun 2024 11:30:58 +0200 Subject: [PATCH 4/9] chore: fix gitignore to include ruby files --- .gitignore | 64 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 64 insertions(+) diff --git a/.gitignore b/.gitignore index d0ecee6..2976ec8 100644 --- a/.gitignore +++ b/.gitignore @@ -4,3 +4,67 @@ lib/ruby/gems .paths build bin/ncn +# Created by https://www.toptal.com/developers/gitignore/api/ruby +# Edit at https://www.toptal.com/developers/gitignore?templates=ruby + +### Ruby ### +*.gem +*.rbc +/.config +/coverage/ +/InstalledFiles +/pkg/ +/spec/reports/ +/spec/examples.txt +/test/tmp/ +/test/version_tmp/ +/tmp/ + +# Used by dotenv library to load environment variables. +# .env + +# Ignore Byebug command history file. +.byebug_history + +## Specific to RubyMotion: +.dat* +.repl_history +build/ +*.bridgesupport +build-iPhoneOS/ +build-iPhoneSimulator/ + +## Specific to RubyMotion (use of CocoaPods): +# +# We recommend against adding the Pods directory to your .gitignore. However +# you should judge for yourself, the pros and cons are mentioned at: +# https://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control +# vendor/Pods/ + +## Documentation cache and generated files: +/.yardoc/ +/_yardoc/ +/doc/ +/rdoc/ + +## Environment normalization: +/.bundle/ +/vendor/bundle +/lib/bundler/man/ + +# for a library or gem, you might want to ignore these files since the code is +# intended to run in multiple environments; otherwise, check them in: +# Gemfile.lock +# .ruby-version +# .ruby-gemset + +# unless supporting rvm < 1.11.0 or doing something fancy, ignore this: +.rvmrc + +# Used by RuboCop. Remote config files pulled in from inherit_from directive. +# .rubocop-https?--* + +# End of https://www.toptal.com/developers/gitignore/api/ruby + +.direnv/ +.envrc From 4acb592358a637becf7e9e89c98824e391bd7211 Mon Sep 17 00:00:00 2001 From: Paul Gierz Date: Fri, 7 Jun 2024 11:38:21 +0200 Subject: [PATCH 5/9] ci: first try to get docs to automatically deploy --- .github/workflows/docs.yml | 64 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 64 insertions(+) create mode 100644 .github/workflows/docs.yml diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..df54961 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,64 @@ +# Sample workflow for building and deploying a Jekyll site to GitHub Pages +name: Deploy Jekyll with GitHub Pages dependencies preinstalled + +on: + # Runs on pushes targeting the default branch + push: + branches: ["main", "feat/yard", "**doc**"] + + # Allows you to run this workflow manually from the Actions tab + workflow_dispatch: + +# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages +permissions: + contents: read + pages: write + id-token: write + +# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. +# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. +concurrency: + group: "pages" + cancel-in-progress: false + +jobs: + # Build job + build: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Setup Pages + uses: actions/configure-pages@v5 + - name: Setup Ruby + uses: uses: ruby/setup-ruby@v1 + - name: Install dependencies + run: | + gem install bundler + bundle install + - name: Generate YARD documentation + run: | + gem install yard + yard doc + mkdir _site + mv doc _site/docs + - name: Build with Jekyll + uses: actions/jekyll-build-pages@v1 + with: + source: ./ + destination: ./_site + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + + # Deployment job + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + needs: build + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 + From e81b4d90341bfa8437bb558bd3964b617a716c1e Mon Sep 17 00:00:00 2001 From: Paul Gierz Date: Fri, 7 Jun 2024 11:39:30 +0200 Subject: [PATCH 6/9] ci: remove double uses from bad copy/paste --- .github/workflows/docs.yml | 11 ++--------- 1 file changed, 2 insertions(+), 9 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index df54961..a6ce4e3 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -1,26 +1,21 @@ # Sample workflow for building and deploying a Jekyll site to GitHub Pages name: Deploy Jekyll with GitHub Pages dependencies preinstalled - on: # Runs on pushes targeting the default branch push: branches: ["main", "feat/yard", "**doc**"] - # Allows you to run this workflow manually from the Actions tab workflow_dispatch: - # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages permissions: contents: read pages: write id-token: write - # Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. # However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. concurrency: group: "pages" cancel-in-progress: false - jobs: # Build job build: @@ -31,7 +26,7 @@ jobs: - name: Setup Pages uses: actions/configure-pages@v5 - name: Setup Ruby - uses: uses: ruby/setup-ruby@v1 + uses: ruby/setup-ruby@v1 - name: Install dependencies run: | gem install bundler @@ -48,8 +43,7 @@ jobs: source: ./ destination: ./_site - name: Upload artifact - uses: actions/upload-pages-artifact@v3 - + uses: actions/upload-pages-artifact@v3 # Deployment job deploy: environment: @@ -61,4 +55,3 @@ jobs: - name: Deploy to GitHub Pages id: deployment uses: actions/deploy-pages@v4 - From eb1f4f2c7cfdd7fd3b01504d923f57a81741f239 Mon Sep 17 00:00:00 2001 From: Paul Gierz Date: Fri, 7 Jun 2024 11:41:47 +0200 Subject: [PATCH 7/9] ci: pin the Ruby version used to build documentation to be identical to the one on levante.dkrz.de --- .github/workflows/docs.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index a6ce4e3..8c6b67c 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -27,6 +27,8 @@ jobs: uses: actions/configure-pages@v5 - name: Setup Ruby uses: ruby/setup-ruby@v1 + with: + ruby-version: 3.0.2 # This is the Ruby version of DRKZ's Levante - name: Install dependencies run: | gem install bundler From 8931eb8e8e8b44038014e83408a9f2298955824a Mon Sep 17 00:00:00 2001 From: Paul Gierz Date: Fri, 7 Jun 2024 11:52:19 +0200 Subject: [PATCH 8/9] ci: fix overwriting documentation website --- .github/workflows/docs.yml | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 8c6b67c..2d0ccf4 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -37,12 +37,10 @@ jobs: run: | gem install yard yard doc - mkdir _site - mv doc _site/docs - name: Build with Jekyll uses: actions/jekyll-build-pages@v1 with: - source: ./ + source: ./doc destination: ./_site - name: Upload artifact uses: actions/upload-pages-artifact@v3 From a11ec88990c70d08aed6533197e3cd7586dbca02 Mon Sep 17 00:00:00 2001 From: Paul Gierz Date: Fri, 7 Jun 2024 12:01:10 +0200 Subject: [PATCH 9/9] ci: fix the artifact name to specifially target the _site directory --- .github/workflows/docs.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 2d0ccf4..2431b1a 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -44,6 +44,9 @@ jobs: destination: ./_site - name: Upload artifact uses: actions/upload-pages-artifact@v3 + with: + artifact-name: site + path: _site # Deployment job deploy: environment: