Deploy YARD documentation on GitHub pages

.github/workflows/documentation.yml

@@ -19,6 +19,7 @@ concurrency:
   cancel-in-progress: false
 
 jobs:
+  # Generate Guides
   build-guides:
     runs-on: ubuntu-latest
     env:
@@ -36,27 +37,55 @@ jobs:
         uses: actions/configure-pages@v5
 
       - name: Build with mdBook
-        run: ./mdbook build
+        run: ./mdbook build # generates ./book directory
 
-      - name: Move into a dedicated subdirectory
-        run: |
-          mkdir -p combined-docs/guides
-          cp -r book/* combined-docs/guides
+      - name: Upload Guides Raw Material
+        uses: actions/upload-artifact@v4
+        with:
+          name: guides-output
+          path: book
 
-      - name: Upload static files as artifact
-        id: deployment
-        uses: actions/upload-pages-artifact@v3
+  # Generate API References
+  build-reference:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build API Reference
+        run: yardoc # generates ./yardoc directory
+      - name: Upload Guides Raw Material
+        uses: actions/upload-artifact@v4
         with:
-          path: combined-docs
+          name: reference-output
+          path: yardoc
 
-  # Deployment job
+  # Merge and Deploy to GitHub Pages
   deploy:
+    needs: [build-guides, build-api]
+    runs-on: ubuntu-latest
     environment:
       name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    runs-on: ubuntu-latest
-    needs: build-guides
+      url: ${{ steps:deployment.outputs.page_url }}
     steps:
+      - name: Create Unified Deployment Directory
+        run: mkdir -p combined-docs
+
+      - name: Download Guides
+        uses: actions/download-artifact@v4
+        with:
+          name: guides-output
+          path: combined-docs/guides
+
+      - name: Download API Reference
+        uses: actions/download-artifact@v4
+        with:
+          name: reference-output
+          path: combined-docs/reference
+
+      - name: Upload Single Pages Artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: combined-docs
+
       - name: Deploy to GitHub Pages
         id: deployment
         uses: actions/deploy-pages@v4

.gitignore

@@ -9,6 +9,7 @@ rdoc
 # yardoc generated
 .yardoc
 /_yardoc/
+yardoc
 
 # mdbook generated
 book

.yardopts

@@ -1 +1,2 @@
 --no-private
+--output-dir yardoc

Gemfile.lock

@@ -172,7 +172,7 @@ GEM
       unicode-emoji (~> 4.1)
     unicode-emoji (4.2.0)
     uri (1.1.1)
-    yard (0.9.38)
+    yard (0.9.44)
 
 PLATFORMS
   ruby

Rakefile

@@ -48,21 +48,4 @@ YARD::Rake::YardocTask.new do |t|
   t.options = ['-m', 'markdown'] # optional
 end
 
-desc 'Publish documentation to gh-pages' # TODO: update and use directory other than doc/
-task :publish do
-  Rake::Task['yard'].invoke
-  `git add .`
-  `git commit -m 'Regenerated documentation'`
-  `git checkout gh-pages`
-  `git clean -fdx`
-  `git checkout master -- doc`
-  `cp -R doc/* .`
-  `git rm -rf doc/`
-  `git add .`
-  `git commit -m 'Regenerated documentation'`
-  `git pull`
-  `git push`
-  `git checkout master`
-end
-
 task default: %i[test rubocop]

lib/dynamoid/associations.rb

@@ -27,11 +27,13 @@ module Associations
     module ClassMethods
       # Declare a +has_many+ association for this document.
       #
-      #   class Category
-      #     include Dynamoid::Document
+      # ```
+      # class Category
+      #   include Dynamoid::Document
       #
-      #     has_many :posts
-      #   end
+      #   has_many :posts
+      # end
+      # ```
       #
       # Association is an enumerable collection and supports following addition
       # operations:
@@ -58,17 +60,19 @@ module ClassMethods
       # the current class and the name doesn't match a name of the current
       # class this name can be specified with +inverse_of+ option:
       #
-      #   class Post
-      #     include Dynamoid::Document
+      # ```
+      # class Post
+      #   include Dynamoid::Document
       #
-      #     belongs_to :item, class_name: 'Tag'
-      #   end
+      #   belongs_to :item, class_name: 'Tag'
+      # end
       #
-      #   class Tag
-      #     include Dynamoid::Document
+      # class Tag
+      #   include Dynamoid::Document
       #
-      #     has_many :posts, inverse_of: :item
-      #   end
+      #   has_many :posts, inverse_of: :item
+      # end
+      # ```
       #
       # @param name [Symbol] the name of the association
       # @param options [Hash] options to pass to the association constructor
@@ -83,11 +87,13 @@ def has_many(name, options = {})
 
       # Declare a +has_one+ association for this document.
       #
-      #   class Image
-      #     include Dynamoid::Document
+      # ```
+      # class Image
+      #   include Dynamoid::Document
       #
-      #     has_one :post
-      #   end
+      #   has_one :post
+      # end
+      # ```
       #
       # Association supports following operations:
       #
@@ -106,17 +112,19 @@ def has_many(name, options = {})
       # class and the name doesn't match a name of the current class this name
       # can be specified with +inverse_of+ option:
       #
-      #   class Post
-      #     include Dynamoid::Document
+      # ```
+      # class Post
+      #   include Dynamoid::Document
       #
-      #     belongs_to :logo, class_name: 'Image'
-      #   end
+      #   belongs_to :logo, class_name: 'Image'
+      # end
       #
-      #   class Image
-      #     include Dynamoid::Document
+      # class Image
+      #   include Dynamoid::Document
       #
-      #     has_one :post, inverse_of: :logo
-      #   end
+      #   has_one :post, inverse_of: :logo
+      # end
+      # ```
       #
       # @param name [Symbol] the name of the association
       # @param options [Hash] options to pass to the association constructor
@@ -131,11 +139,13 @@ def has_one(name, options = {})
 
       # Declare a +belongs_to+ association for this document.
       #
-      #   class Post
-      #     include Dynamoid::Document
+      # ```
+      # class Post
+      #   include Dynamoid::Document
       #
-      #     belongs_to :categories
-      #   end
+      #   belongs_to :categories
+      # end
+      # ```
       #
       # Association supports following operations:
       #
@@ -154,17 +164,19 @@ def has_one(name, options = {})
       # the current class and the name doesn't match a name of the current
       # class this name can be specified with +inverse_of+ option:
       #
-      #   class Category
-      #     include Dynamoid::Document
+      # ```
+      # class Category
+      #   include Dynamoid::Document
       #
-      #     has_many :items, class_name: 'Post'
-      #   end
+      #   has_many :items, class_name: 'Post'
+      # end
       #
-      #   class Post
-      #     include Dynamoid::Document
+      # class Post
+      #   include Dynamoid::Document
       #
-      #     belongs_to :categories, inverse_of: :items
-      #   end
+      #   belongs_to :categories, inverse_of: :items
+      # end
+      # ```
       #
       # By default a hash key attribute name is +id+. If an associated class
       # uses another name for a hash key attribute it should be specified in
@@ -186,11 +198,13 @@ def belongs_to(name, options = {})
 
       # Declare a +has_and_belongs_to_many+ association for this document.
       #
-      #   class Post
-      #     include Dynamoid::Document
+      # ```
+      # class Post
+      #   include Dynamoid::Document
       #
-      #     has_and_belongs_to_many :tags
-      #   end
+      #   has_and_belongs_to_many :tags
+      # end
+      # ```
       #
       # Association is an enumerable collection and supports following addition
       # operations:
@@ -217,17 +231,19 @@ def belongs_to(name, options = {})
       # the current class and the name doesn't match a name of the current
       # class this name can be specified with +inverse_of+ option:
       #
-      #   class Tag
-      #     include Dynamoid::Document
+      # ```
+      # class Tag
+      #   include Dynamoid::Document
       #
-      #     has_and_belongs_to_many :items, class_name: 'Post'
-      #   end
+      #   has_and_belongs_to_many :items, class_name: 'Post'
+      # end
       #
-      #   class Post
-      #     include Dynamoid::Document
+      # class Post
+      #   include Dynamoid::Document
       #
-      #     has_and_belongs_to_many :tags, inverse_of: :items
-      #   end
+      #   has_and_belongs_to_many :tags, inverse_of: :items
+      # end
+      # ```
       #
       # @param name [Symbol] the name of the association
       # @param options [Hash] options to pass to the association constructor

lib/dynamoid/associations/association.rb

@@ -6,9 +6,10 @@ module Dynamoid
   # The target is the object which is referencing by this association.
   # @private
   module Associations
-    # @private
     module Association
-      attr_accessor :name, :options, :source, :loaded
+      attr_accessor :name, :options, :source
+      # @private
+      attr_accessor :loaded
 
       # Create a new association.
       #
@@ -30,12 +31,15 @@ def initialize(source, name, options)
         @loaded = false
       end
 
+      # @private
       def loaded?
         @loaded
       end
 
+      # @private
       def find_target; end
 
+      # @private
       def target
         unless loaded?
           @target = find_target
@@ -45,19 +49,23 @@ def target
         @target
       end
 
+      # @private
       def reset
         @target = nil
         @loaded = false
       end
 
+      # @private
       def declaration_field_name
         "#{name}_ids"
       end
 
+      # @private
       def declaration_field_type
         :set
       end
 
+      # @private
       def disassociate_source
         Array(target).each do |target_entry|
           target_entry.send(target_association).disassociate(source.hash_key) if target_entry && target_association

lib/dynamoid/associations/belongs_to.rb

@@ -4,14 +4,15 @@ module Dynamoid
   # The belongs_to association. For belongs_to, we reference only a single target instead of multiple records; that target is the
   # object to which the association object is associated.
   module Associations
-    # @private
     class BelongsTo
       include SingleAssociation
 
+      # @private
       def declaration_field_name
         options[:foreign_key] || "#{name}_ids"
       end
 
+      # @private
       def declaration_field_type
         if options[:foreign_key]
           target_class.attributes[target_class.hash_key][:type]
@@ -20,6 +21,7 @@ def declaration_field_type
         end
       end
 
+      # @private
       # Override default implementation
       # to handle case when we store id as scalar value, not as collection
       def associate(hash_key)

lib/dynamoid/associations/has_and_belongs_to_many.rb

@@ -3,7 +3,6 @@
 module Dynamoid
   # The has and belongs to many association.
   module Associations
-    # @private
     class HasAndBelongsToMany
       include ManyAssociation
 

lib/dynamoid/associations/has_many.rb

@@ -3,7 +3,6 @@
 module Dynamoid
   # The has_many association.
   module Associations
-    # @private
     class HasMany
       include ManyAssociation