Merge pull request #129 from halorrr/add-and-configure-yard-docs

Add and configure yard docs

.github/workflows/build_and_public_yard_docs.yml

@@ -0,0 +1,47 @@
+name: Build and Publish Yard Docs
+
+on:
+  push:
+    branches: [ main ]
+  workflow_dispatch:
+
+permissions:
+    contents: read
+    pages: write
+    id-token: write
+
+concurrency:
+    group: "pages"
+    cancel-in-progress: true
+
+jobs:
+  build:
+    name: Build and Publish Yard Docs
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1.165.1
+        with:
+          ruby-version: 3.3.0
+          bundler-cache: true
+
+      - name: Install YARD
+        run: gem install yard
+
+      - name: Generate docs
+        run: yard docs
+
+      - name: Setup Github Pages
+        uses: actions/configure-pages@v4
+
+      - name: Upload Artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: "doc"
+
+      - name: Publish to Github Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.yardopts

@@ -0,0 +1,2 @@
+--plugin yard-sorbet
+--markup markdown

Gemfile

@@ -18,3 +18,5 @@ gem "sorbet-static-and-runtime", require: false
 gem "spoom", require: false
 gem "tapioca", require: false
 gem "dotenv"
+gem "yard", require: false
+gem "yard-sorbet", require: false

Gemfile.lock

@@ -148,6 +148,8 @@ DEPENDENCIES
   spoom
   tapioca
   toys
+  yard
+  yard-sorbet
 
 BUNDLED WITH
    2.5.3

bin/yard

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'yard' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+
+bundle_binstub = File.expand_path("bundle", __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300).include?("This file was generated by Bundler")
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("yard", "yard")

lib/lunchmoney.rb

@@ -8,16 +8,28 @@
 require "sorbet-runtime"
 
 # Include T::Sig directly in the module class so that it doesn't need to be extended everywhere.
-Module.include(T::Sig)
+class Module
+  include T::Sig
+end
 
 require_relative "lunchmoney/version"
 require_relative "lunchmoney/validators"
 require_relative "lunchmoney/api"
 
 module LunchMoney
+  # Lock used to avoid config conflicts
   LOCK = T.let(Mutex.new, Mutex)
 
   class << self
+    # @example Set your API key
+    #   LunchMoney.configure do |config|
+    #     config.api_key = "your_api_key"
+    #   end
+    #
+    # @example Turn off object validation
+    #   LunchMoney.configure do |config|
+    #     config.validate_object_attributes = false
+    #   end
     sig do
       params(block: T.proc.params(arg0: LunchMoney::Configuration).void).void
     end

lib/lunchmoney/api.rb

@@ -17,6 +17,9 @@
 require_relative "crypto/crypto_calls"
 
 module LunchMoney
+  # The main API class that a user should interface through the method of any individual call is delegated through here
+  # so that it is never necessary to go through things like `LunchMoney::UserCalls.new.user` instead you can directly
+  # call the endpoint with LunchMoney::Api.new.user and it will be delegated to the correct call.
   class Api
     sig { returns(T.nilable(String)) }
     attr_reader :api_key

lib/lunchmoney/api_call.rb

@@ -4,7 +4,9 @@
 require_relative "error"
 
 module LunchMoney
+  # Base class for all API call types
   class ApiCall
+    # Base URL used for API calls
     BASE_URL = "https://dev.lunchmoney.app/v1/"
 
     sig { returns(T.nilable(String)) }

lib/lunchmoney/assets/asset.rb

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 module LunchMoney
+  # https://lunchmoney.dev/#assets-object
   class Asset < LunchMoney::DataObject
     # API object reference documentation: https://lunchmoney.dev/#assets-object
 
@@ -25,6 +26,7 @@ class Asset < LunchMoney::DataObject
     sig { returns(T::Boolean) }
     attr_accessor :exclude_transactions
 
+    # Valid asset type names
     VALID_TYPE_NAMES = T.let(
       [
         "cash",
@@ -41,6 +43,7 @@ class Asset < LunchMoney::DataObject
       T::Array[String],
     )
 
+    # Valid asset subtype names
     VALID_SUBTYPE_NAMES = T.let(
       [
         "retirement",

lib/lunchmoney/assets/asset_calls.rb

@@ -4,6 +4,7 @@
 require_relative "asset"
 
 module LunchMoney
+  # https://lunchmoney.dev/#assets
   class AssetCalls < ApiCall
     sig { returns(T.any(T::Array[LunchMoney::Asset], LunchMoney::Errors)) }
     def assets

lib/lunchmoney/budget/budget.rb

@@ -5,6 +5,7 @@
 require_relative "config"
 
 module LunchMoney
+  # https://lunchmoney.dev/#budget-object
   class Budget < LunchMoney::DataObject
     # API object reference documentation: https://lunchmoney.dev/#budget-object
 

lib/lunchmoney/budget/budget_calls.rb

@@ -4,6 +4,7 @@
 require_relative "budget"
 
 module LunchMoney
+  # https://lunchmoney.dev/#budget
   class BudgetCalls < ApiCall
     sig do
       params(

lib/lunchmoney/budget/config.rb

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 module LunchMoney
+  # https://lunchmoney.dev/#config-object
   class Config < LunchMoney::DataObject
     # API object reference documentation: https://lunchmoney.dev/#config-object
 

lib/lunchmoney/budget/data.rb

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 module LunchMoney
+  # https://lunchmoney.dev/#data-object
   class Data < LunchMoney::DataObject
     # API object reference documentation: https://lunchmoney.dev/#data-object
 

lib/lunchmoney/categories/category.rb

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 module LunchMoney
+  # https://lunchmoney.dev/#categories-object
   class Category < LunchMoney::DataObject
     sig { returns(Integer) }
     attr_accessor :id

lib/lunchmoney/categories/category_calls.rb

@@ -4,7 +4,9 @@
 require_relative "category"
 
 module LunchMoney
+  # https://lunchmoney.dev/#categories
   class CategoryCalls < ApiCall
+    # Valid query parameter formets for categories
     VALID_FORMATS = T.let(
       [
         "flattened",

lib/lunchmoney/configuration.rb

@@ -2,6 +2,14 @@
 # frozen_string_literal: true
 
 module LunchMoney
+  # Holds global configuration options for this gem
+  # @example api_key
+  #   LunchMoney::Configuration.api_key
+  #   => "your_api_key"
+  #
+  # @example validate_object_attributes
+  #   LunchMoney::Configuration.validate_object_attributes
+  #   => true
   class Configuration
     sig { returns(T.nilable(String)) }
     attr_accessor :api_key

lib/lunchmoney/crypto/crypto.rb

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 module LunchMoney
+  # https://lunchmoney.dev/#crypto-object
   class Crypto < LunchMoney::DataObject
     sig { returns(T.nilable(Integer)) }
     attr_accessor :id, :zabo_account_id

lib/lunchmoney/crypto/crypto_calls.rb

@@ -4,6 +4,7 @@
 require_relative "crypto"
 
 module LunchMoney
+  # https://lunchmoney.dev/#crypto
   class CryptoCalls < ApiCall
     sig { returns(T.any(T::Array[LunchMoney::Crypto], LunchMoney::Errors)) }
     def crypto

lib/lunchmoney/data_object.rb

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 module LunchMoney
+  # Base data object for the objects returned and used when calling the LunchMoney API
   class DataObject
     sig { params(symbolize_keys: T::Boolean).returns(T::Hash[String, T.untyped]) }
     def serialize(symbolize_keys: false)

lib/lunchmoney/error.rb

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 module LunchMoney
+  # This class is used to represent errors returned directly from the LunchMoney API
   class Error
     sig { returns(String) }
     attr_reader :message
@@ -13,4 +14,5 @@ def initialize(message:)
   end
 end
 
+# A type alias for an array of LunchMoney::Error
 LunchMoney::Errors = T.type_alias { T::Array[LunchMoney::Error] }

lib/lunchmoney/exceptions.rb

@@ -2,11 +2,15 @@
 # frozen_string_literal: true
 
 module LunchMoney
+  # Base exception class for exceptions raised by this gem
   class Exception < StandardError; end
 
+  # Exception raised when an API Key appears to be invalid
   class InvalidApiKey < Exception; end
 
+  # Exception raised when an object attribute is invalid
   class InvalidObjectAttribute < Exception; end
 
+  # Exception raised when a query parameter is invalid
   class InvalidQueryParameter < Exception; end
 end

lib/lunchmoney/plaid_accounts/plaid_account.rb

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 module LunchMoney
+  # https://lunchmoney.dev/#plaid-accounts-object
   class PlaidAccount < LunchMoney::DataObject
     sig { returns(Integer) }
     attr_accessor :id

lib/lunchmoney/plaid_accounts/plaid_account_calls.rb

@@ -4,6 +4,7 @@
 require_relative "plaid_account"
 
 module LunchMoney
+  # https://lunchmoney.dev/#plaid-accounts
   class PlaidAccountCalls < ApiCall
     sig { returns(T.any(T::Array[LunchMoney::PlaidAccount], LunchMoney::Errors)) }
     def plaid_accounts

lib/lunchmoney/recurring_expenses/recurring_expense.rb

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 module LunchMoney
+  # https://lunchmoney.dev/#recurring-expenses-object
   class RecurringExpense < LunchMoney::DataObject
     sig { returns(Integer) }
     attr_accessor :id, :amount

lib/lunchmoney/recurring_expenses/recurring_expense_calls.rb

@@ -4,6 +4,7 @@
 require_relative "recurring_expense"
 
 module LunchMoney
+  # https://lunchmoney.dev/#recurring-expenses
   class RecurringExpenseCalls < ApiCall
     sig do
       params(

lib/lunchmoney/tags/tag.rb

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 module LunchMoney
+  # https://lunchmoney.dev/#tags-object
   class Tag < LunchMoney::DataObject
     sig { returns(Integer) }
     attr_accessor :id

lib/lunchmoney/tags/tag_calls.rb

@@ -4,6 +4,7 @@
 require_relative "tag"
 
 module LunchMoney
+  # https://lunchmoney.dev/#tags
   class TagCalls < ApiCall
     sig { returns(T.any(T::Array[LunchMoney::Tag], LunchMoney::Errors)) }
     def all_tags

lib/lunchmoney/transactions/split.rb

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 module LunchMoney
+  # Object used to split a transaction when updating https://lunchmoney.dev/#update-transaction
   class Split < LunchMoney::DataObject
     sig { returns(T.nilable(String)) }
     attr_accessor :payee, :date, :notes

lib/lunchmoney/transactions/transaction.rb

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 module LunchMoney
+  # https://lunchmoney.dev/#transaction-object
   class Transaction < LunchMoney::DataObject
     sig { returns(T.nilable(Integer)) }
     attr_accessor :id, :to_base, :category_id, :recurring_id, :asset_id, :plaid_account_id, :parent_id, :group_id

lib/lunchmoney/transactions/transaction_calls.rb

@@ -6,6 +6,7 @@
 require_relative "split"
 
 module LunchMoney
+  # https://lunchmoney.dev/#transactions
   class TransactionCalls < ApiCall
     sig do
       params(

lib/lunchmoney/transactions/update_transaction.rb

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 module LunchMoney
+  # object used when updating a transaction https://lunchmoney.dev/#update-transaction
   class UpdateTransaction < LunchMoney::DataObject
     sig { returns(T.nilable(String)) }
     attr_accessor :date, :payee, :amount, :currency, :notes, :status, :external_id

lib/lunchmoney/user/user.rb

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 module LunchMoney
+  # https://lunchmoney.dev/#user-object
   class User < LunchMoney::DataObject
     sig { returns(Integer) }
     attr_accessor :user_id, :account_id

lib/lunchmoney/user/user_calls.rb

@@ -4,6 +4,7 @@
 require_relative "user"
 
 module LunchMoney
+  # https://lunchmoney.dev/#user
   class UserCalls < ApiCall
     sig { returns(T.any(LunchMoney::User, LunchMoney::Errors)) }
     def user

lib/lunchmoney/validators.rb

@@ -4,6 +4,7 @@
 require "time"
 
 module LunchMoney
+  # module containing reusable methods for validating data objects
   module Validators
     include Kernel