Merge pull request #4283 from sanger/develop

Develop -> Master

.github/workflows/generate_pages.yml

@@ -0,0 +1,41 @@
+name: Deploy Yard to GitHub Pages
+
+on:
+  push:
+    branches:
+      - "master"
+  workflow_dispatch:
+
+permissions:
+  pages: write # Allow writing to the GitHub Pages
+  id-token: write # Allow OIDC token to be issued
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true
+
+      - name: Generate Yard documentation
+        run: |
+          bundle exec yard doc
+
+      - name: Upload artifact to GitHub Pages
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: doc # Path to the folder containing the Yard documentation (default is 'doc')
+
+  deploy:
+    runs-on: ubuntu-latest
+    needs: build # The deploy job will only run if the build job is successful
+
+    steps:
+      - name: Deploy to GitHub Pages
+        uses: actions/deploy-pages@v4

.github/workflows/ruby_test.yml

@@ -8,6 +8,13 @@ env:
   KNAPSACK_PRO_LOG_LEVEL: info
   SKIP_AUTOMATIC_GEM_INSTALLATION: true # Disable the bundle install in bin/setup
 
+########
+## Warning!
+## CodeCov's config in `codecov.yml` is expecting an exact number of builds to complete before it will run.
+## See the config value with key `after_n_builds` in that file.
+## If the number of build steps changes, it is important to update the count there to match.
+########
+
 on:
   - push
   - pull_request

.release-version

@@ -1 +1 @@
-14.40.0
+14.41.0

.yardopts

@@ -1,4 +1,7 @@
+--markup=markdown
 --asset docs/images:images
+--exclude app/controllers/api/v2/[^/]*\.rb
+--exclude app/controllers/api/v2/concerns/.*
 -
 LICENSE
 docs/*.md

Gemfile.lock

@@ -299,9 +299,9 @@ GEM
       net-protocol
     netrc (0.11.0)
     nio4r (2.7.3)
-    nokogiri (1.16.6-arm64-darwin)
+    nokogiri (1.16.7-arm64-darwin)
       racc (~> 1.4)
-    nokogiri (1.16.6-x86_64-linux)
+    nokogiri (1.16.7-x86_64-linux)
       racc (~> 1.4)
     parallel (1.24.0)
     parser (3.3.0.5)
@@ -320,7 +320,7 @@ GEM
     public_suffix (6.0.0)
     puma (6.4.2)
       nio4r (~> 2.0)
-    racc (1.8.0)
+    racc (1.8.1)
     rack (2.2.9)
     rack-acceptable (0.1.0)
       rack (>= 1.1.0)

README.md

@@ -27,52 +27,66 @@ a organisation of 900 people.
 
 <!-- toc -->
 
-- [Documentation](#documentation)
-- [Requirements](#requirements)
-- [Getting started (using Docker)](#getting-started-using-docker)
-- [Getting started (using native installation)](#getting-started-using-native-installation)
-  - [Installing ruby](#installing-ruby)
-    - [rbenv](#rbenv)
-  - [Automatic Sequencescape setup](#automatic-sequencescape-setup)
-  - [Manual Sequencescape setup](#manual-sequencescape-setup)
-    - [Installing gems](#installing-gems)
-    - [Adjusting config](#adjusting-config)
-    - [Default setup](#default-setup)
-  - [Starting rails](#starting-rails)
-    - [Delayed job](#delayed-job)
-  - [Message broker](#message-broker)
-- [Testing](#testing)
-- [Linting and formatting](#linting-and-formatting)
-- [Rake tasks](#rake-tasks)
-- [Supporting applications](#supporting-applications)
-  - [Barcode printing](#barcode-printing)
-  - [Plate barcode service](#plate-barcode-service)
-  - [Data warehousing](#data-warehousing)
-- [Miscellaneous](#miscellaneous)
-  - [Lefthook](#lefthook)
-  - [Ruby warnings and rake 11](#ruby-warnings-and-rake-11)
-  - [NPG - Illumina tracking software](#npg---illumina-tracking-software)
-  - [Troubleshooting](#troubleshooting)
-    - [MySQL errors when installing](#mysql-errors-when-installing)
-    - [Installing on Apple Silicon (M1)](#installing-on-apple-silicon-m1)
-  - [API V2 Authentication](#api-v2-authentication)
-  - [Publishing AMQP Messages](#publishing-amqp-messages)
-  - [Updating the table of contents](#updating-the-table-of-contents)
-  - [CI](#ci)
+- [ Sequencescape](#-sequencescape)
+  - [Contents](#contents)
+  - [Documentation](#documentation)
+    - [Linting](#linting)
+  - [Requirements](#requirements)
+  - [Getting started (using Docker)](#getting-started-using-docker)
+  - [Getting started (using native installation)](#getting-started-using-native-installation)
+    - [Installing ruby](#installing-ruby)
+      - [rbenv](#rbenv)
+    - [Automatic Sequencescape setup](#automatic-sequencescape-setup)
+    - [Manual Sequencescape setup](#manual-sequencescape-setup)
+      - [Installing gems](#installing-gems)
+      - [Adjusting config](#adjusting-config)
+      - [Default setup](#default-setup)
+    - [Starting rails](#starting-rails)
+      - [Delayed job](#delayed-job)
+    - [Message broker](#message-broker)
+  - [Testing](#testing)
+  - [Linting and formatting](#linting-and-formatting)
+  - [Rake tasks](#rake-tasks)
+  - [Supporting applications](#supporting-applications)
+    - [Barcode printing](#barcode-printing)
+    - [Plate barcode service](#plate-barcode-service)
+    - [Data warehousing](#data-warehousing)
+  - [Miscellaneous](#miscellaneous)
+    - [Lefthook](#lefthook)
+    - [Ruby warnings and rake 11](#ruby-warnings-and-rake-11)
+    - [NPG - Illumina tracking software](#npg---illumina-tracking-software)
+    - [Troubleshooting](#troubleshooting)
+      - [MySQL errors when installing](#mysql-errors-when-installing)
+      - [Installing on Apple Silicon (M1)](#installing-on-apple-silicon-m1)
+    - [API V2 Authentication](#api-v2-authentication)
+    - [Publishing AMQP Messages](#publishing-amqp-messages)
+    - [Updating the table of contents](#updating-the-table-of-contents)
+    - [CI](#ci)
+    - [ERD](#erd)
 
 <!-- tocstop -->
 
 ## Documentation
 
-In addition to the [externally hosted YARD docs](https://www.rubydoc.info/github/sanger/sequencescape), you can also run a local server:
+The Yard documentation is also hosted at [GitHub Pages](https://pages.github.com/) under [https://sanger.github.io/sequencescape/](https://sanger.github.io/sequencescape/).
+The documentation is automatically updated via a CI workflow when a merge to master occurs, but you can also trigger it manually against any branch (the branch can be selected using the "Run Workflow" button in the [corresponding action](https://github.com/sanger/sequencescape/actions/workflows/generate_pages.yml)).
+
+To preview this documentation, you can spin up a yard server locally using the following command:
 
 ```shell
-yard server -r --gems -m sequencescape .
+yard server --reload sequencescape
 ```
 
-You can then access the Sequencescape documentation through: [http://localhost:8808/docs/sequencescape](http://localhost:8808/docs/sequencescape)
+You can then access the Sequencescape documentation through: [http://localhost:8808/docs](http://localhost:8808/docs)
+
+If the server complains that the stack depth is too deep, this only appears to be a problem when you try to view the documentation without pre-compiling it.
+Precompiling is the simple solution and can be achieved with the following.
+
+```shell
+yard doc sequencescape
+```
 
-Yard will also try and document the installed gems: [http://localhost:8808/docs](http://localhost:8808/docs)
+This will pre-fill the cache and allow the server command above to display the documentation without complaining about stack depths.
 
 ### Linting
 
@@ -454,3 +468,15 @@ npx markdown-toc -i README.md --bullets "-"
 The GH actions builds use the Knapsack-pro gem to reduce build time by parallelizing the RSpec and Cucumber tests. There is no need to regenerate the knapsack_rspec_report.json file, Knapsack Pro will dynamically allocate tests to ensure tests finish as close together as possible.
 
 Copyright (c) 2007, 2010-2021 Genome Research Ltd.
+
+### ERD
+
+You can create a database entity relationship diagram, by specifying the title and attributes optionally, and view the output:
+
+```
+bundle exec rake erd title='Sequencescape Entity Relationship Diagram' attributes='primary_keys,foreign_keys,inheritance' orientation=horizontal polymorphism=true notation=bachman indirect=false inheritance=true only='Sample,Study,AliquotIndex,Aliquot,Project,Order,Submission,Labware,Receptacle,Request,Request::Metadata,Batch,BatchRequest,LabEvent,RequestType,Pipeline,SampleManifest,Sample::Metadata,Study::Metadata,Item,BaitLibrary,RequestEvent,Project::Metadata,Barcode,Purpose,QCResult,QCAssay,User,Plate,Tube,Well' exclude='Target,Commentable,Failable,Eventful,Eventable,Resource,Attributable,Owner,Authorizable,Documentable'
+
+open erd.pdf
+```
+
+The command uses the [rails-erd](https://github.com/voormedia/rails-erd) gem.

app/controllers/api/v2/tag_group_adapter_types_controller.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Api
+  module V2
+    # Provides a JSON API controller for TagGroup::AdapterType
+    # See: http://jsonapi-resources.com/ for JSONAPI::Resource documentation
+    class TagGroupAdapterTypesController < JSONAPI::ResourceController
+      # By default JSONAPI::ResourceController provides most the standard
+      # behaviour, and in many cases this file may be left empty.
+    end
+  end
+end

app/controllers/api/v2/tube_rack_statuses_controller.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Api
+  module V2
+    # Provides a JSON API controller for TubeRackStatus
+    # See: http://jsonapi-resources.com/ for JSONAPI::Resource documentation
+    class TubeRackStatusesController < JSONAPI::ResourceController
+      # By default JSONAPI::ResourceController provides most the standard
+      # behaviour, and in many cases this file may be left empty.
+    end
+  end
+end

app/models/api/study_io.rb

@@ -100,5 +100,6 @@ def render_class
     map_attribute_to_json_attribute(:s3_email_list)
     map_attribute_to_json_attribute(:data_deletion_period)
     map_attribute_to_json_attribute(:contaminated_human_data_access_group)
+    with_association(:program, lookup_by: :id) { map_attribute_to_json_attribute(:name, 'programme') }
   end
 end

app/models/tag_set.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+# Links together two related tag groups - i7 and i5 - to represent a dual index tag set
+# It can also be used to represent single index tag sets
+# Background explained in Y24-170 (https://github.com/sanger/sequencescape/issues/4160)
+class TagSet < ApplicationRecord
+  # For dual index tags, tag_group is i7 oligos and tag2_group is i5 oligos
+  belongs_to :tag_group, class_name: 'TagGroup', optional: false
+  belongs_to :tag2_group, class_name: 'TagGroup', optional: true
+
+  # We can assume adapter_type is the same for both tag groups
+  # But tag2_group may not be present so we delegate to tag_group
+  delegate :adapter_type, to: :tag_group
+
+  validates :name, presence: true, uniqueness: true
+  validate :tag_group_adapter_types_must_match
+
+  # Dynamic method to determine the visibility of a tag_set based on the visibility of its tag_groups
+  def visible
+    tag_group.visible && (tag2_group.nil? || tag2_group.visible)
+  end
+
+  # Method to determine that both tag groups have the same adapter type
+  def tag_group_adapter_types_must_match
+    return unless tag2_group && tag_group.adapter_type != tag2_group.adapter_type
+    errors.add(:tag_group, 'Adapter types of tag groups must match')
+  end
+
+  def tag_group_name=(name)
+    self.tag_group = TagGroup.find_by!(name: name)
+  end
+
+  def tag2_group_name=(name)
+    self.tag2_group = TagGroup.find_by!(name: name)
+  end
+end

app/resources/api/v2/aliquot_resource.rb

@@ -2,11 +2,18 @@
 
 module Api
   module V2
-    # Provides a JSON API representation of aliquot
-    # See: http://jsonapi-resources.com/ for JSONAPI::Resource documentation
+    # @todo This documentation does not yet include a detailed description of what this resource represents.
+    # @todo This documentation does not yet include detailed descriptions for relationships, attributes and filters.
+    # @todo This documentation does not yet include any example usage of the API via cURL or similar.
+    #
+    # @note Access this resource via the `/api/v2/aliquots/` endpoint.
+    #
+    # Provides a JSON:API representation of {Aliquot}.
+    #
+    # For more information about JSON:API see the [JSON:API Specifications](https://jsonapi.org/format/)
+    # or look at the [JSONAPI::Resources](http://jsonapi-resources.com/) package for Sequencescape's implementation
+    # of the JSON:API standard.
     class AliquotResource < BaseResource
-      # immutable # comment to make the resource mutable
-
       default_includes :tag, :tag2
 
       # Associations

app/resources/api/v2/asset_audit_resource.rb

@@ -2,33 +2,42 @@
 
 module Api
   module V2
-    # Provides a JSON API representation of AssetAudit
-    # See: http://jsonapi-resources.com/ for JSONAPI::Resource documentation
+    # @todo This documentation does not yet include a detailed description of what this resource represents.
+    # @todo This documentation does not yet include detailed descriptions for relationships, attributes and filters.
+    # @todo This documentation does not yet include any example usage of the API via cURL or similar.
+    #
+    # @note Access this resource via the `/api/v2/asset_audits/` endpoint.
+    #
+    # Provides a JSON:API representation of {AssetAudit}.
+    #
+    # For more information about JSON:API see the [JSON:API Specifications](https://jsonapi.org/format/)
+    # or look at the [JSONAPI::Resources](http://jsonapi-resources.com/) package for Sequencescape's implementation
+    # of the JSON:API standard.
     class AssetAuditResource < BaseResource
       model_name 'AssetAudit'
 
       # @!attribute key
-      #  @return [String] the key of the asset audit.
+      #   @return [String] the key of the asset audit.
       attribute :key
 
       # @!attribute message
-      #  @return [String] the message of the asset audit.
+      #   @return [String] the message of the asset audit.
       attribute :message
 
       # @!attribute created_by
-      #  @return [String] the user who created the asset audit.
+      #   @return [String] the user who created the asset audit.
       attribute :created_by
 
       # @!attribute asset_uuid
-      #  @return [String] the uuid of the asset associated with the asset audit.
+      #   @return [String] the uuid of the asset associated with the asset audit.
       attribute :asset_uuid
 
       # @!attribute witnessed_by
-      #  @return [String] the user who witnessed the asset audit.
+      #   @return [String] the user who witnessed the asset audit.
       attribute :witnessed_by
 
       # @!attribute metadata
-      #  @return [Hash] the metadata of the asset audit.
+      #   @return [Hash] the metadata of the asset audit.
       attribute :metadata # Currently known clients (AssetAudits app) are sending null; unsure of the expected format.
 
       # Sets the Asset on the model using the UUID provided in the API create/update request.

app/resources/api/v2/asset_resource.rb

@@ -2,7 +2,17 @@
 
 module Api
   module V2
-    # AssetResource
+    # @todo This documentation does not yet include a detailed description of what this resource represents.
+    # @todo This documentation does not yet include detailed descriptions for relationships, attributes and filters.
+    # @todo This documentation does not yet include any example usage of the API via cURL or similar.
+    #
+    # @note Access this resource via the `/api/v2/assets/` endpoint.
+    #
+    # Provides a JSON:API representation of {Asset}.
+    #
+    # For more information about JSON:API see the [JSON:API Specifications](https://jsonapi.org/format/)
+    # or look at the [JSONAPI::Resources](http://jsonapi-resources.com/) package for Sequencescape's implementation
+    # of the JSON:API standard.
     class AssetResource < BaseResource
       attributes :uuid
 

app/resources/api/v2/base_resource.rb

@@ -2,8 +2,17 @@
 
 module Api
   module V2
-    # Provides extensions to JSONAPI::Resource as well as global behaviour
-    # See: http://jsonapi-resources.com/ for JSONAPI::Resource documentation
+    # @api V2
+    # @abstract
+    #
+    # @todo This documentation does not yet include complete descriptions of methods and what this class offers to its
+    #   sub-classes.
+    #
+    # Provides a base class for JSON:API representations of {ApplicationRecord} sub-classes.
+    #
+    # For more information about JSON:API see the [JSON:API Specifications](https://jsonapi.org/format/)
+    # or look at the [JSONAPI::Resources](http://jsonapi-resources.com/) package for Sequencescape's implementation
+    # of the JSON:API standard.
     class BaseResource < JSONAPI::Resource
       abstract