Merge pull request #53 from piotr-iohk/docs

Docs

.github/workflows/docs.yml

@@ -0,0 +1,50 @@
+name: Docs
+
+on:
+  push:
+    branches:
+      - master
+    tags:
+      - '*'
+  pull_request:
+
+jobs:
+  build:
+    name: Build + Publish Docs
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: '📥 Checkout repository'
+      uses: actions/checkout@v2
+    - name: '💎 Setup Ruby'
+      uses: actions/setup-ruby@v1
+
+    - name: '🔧 Set versions'
+      id: versions
+      run: |
+        if [[ $GITHUB_REF =~ ^refs/tags/ ]]; then
+          version="${GITHUB_REF/refs\/tags\//}"
+          commit_message="Release $version"
+        else
+          version=master
+          commit_message="Master"
+        fi
+        echo "::set-output name=commit_message::$commit_message"
+        echo "::set-output name=version::$version"
+
+    - name: '🔨 Build'
+      run: |
+        gem install yard
+        readme_link=https://github.com/piotr-iohk/cardano-wallet-rb/blob/${{ steps.versions.outputs.version }}/README.md
+        yard doc --title "Documentation for cardano_wallet (${{ steps.versions.outputs.version }})"
+        sed -i "s|<a href=\"index.html\" title=\"README\">|<a href=\"$readme_link\" title=\"README\">|" ./doc/_index.html
+        cp ./doc/_index.html ./doc/index.html
+
+    - name: '🚀 Publish'
+      if: ${{ github.ref == 'refs/heads/master' || startsWith(github.ref, 'refs/tags') }}
+      uses: peaceiris/actions-gh-pages@v3
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: doc
+        destination_dir: ${{ steps.versions.outputs.version }}
+        full_commit_message: ${{ steps.versions.outputs.commit_message }}

README.md

@@ -1,5 +1,3 @@
-
-
 <a href="https://badge.fury.io/rb/cardano_wallet">
   <img src="https://badge.fury.io/rb/cardano_wallet.svg" alt="Gem Version">
 </a>
@@ -9,7 +7,9 @@
 <a href="https://github.com/piotr-iohk/cardano-wallet-rb/actions?query=workflow%3ATests">
   <img src="https://github.com/piotr-iohk/cardano-wallet-rb/workflows/Tests/badge.svg" />
 </a>
-
+<a href="https://github.com/piotr-iohk/cardano-wallet-rb/actions?query=workflow%3ADocs">
+  <img src="https://github.com/piotr-iohk/cardano-wallet-rb/workflows/Docs/badge.svg" />
+</a>
 
 # cardano-wallet-rb
 
@@ -32,9 +32,12 @@ Or:
 
 ## Documentation
 
-For ruby doc see: https://rubydoc.info/gems/cardano_wallet.
+| Link | Description  |
+|--|--|
+|  [Ruby API (edge)](https://piotr-iohk.github.io/cardano-wallet-rb/master/) | cardano-wallet-rb API |
+|[REST API (edge)](https://input-output-hk.github.io/cardano-wallet/api/edge/)| [cardano-wallet's](https://github.com/input-output-hk/cardano-wallet) REST API|
 
-For `cardano-wallet` REST Api see: https://input-output-hk.github.io/cardano-wallet/api/edge/.
+> :warning: Links point to `edge` APIs corresponding to `master` branches for both cardano-wallet and cardano-wallet-rb. Refer to [release page](https://github.com/piotr-iohk/cardano-wallet-rb/releases) for API doc suitable for the latest release.
 
 ## Examples
 
@@ -96,9 +99,6 @@ MISC.proxy.submit_external_transaction(File.new("/tmp/blob.bin").read)
 MISC.utils.addresses("addr_test1vqrlltfahghjxl5sy5h5mvfrrlt6me5fqphhwjqvj5jd88cccqcek")
 ```
 
-Refer to [documentation](https://rubydoc.info/gems/cardano_wallet) for more details.
-
-
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/piotr-iohk/cardano-wallet-rb. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/piotr-iohk/cardano-wallet-rb/blob/master/CODE_OF_CONDUCT.md).

lib/cardano_wallet.rb

@@ -12,7 +12,7 @@
 require_relative 'cardano_wallet/shared'
 
 ##
-# Main module
+# Main module. Go to {Base.initialize} for more details no how to start.
 module CardanoWallet
   def self.new(options = {})
     CardanoWallet::Base.new(options)

lib/cardano_wallet/base.rb

@@ -8,6 +8,16 @@ class Base
 
     attr_accessor :opt
 
+    # Initialize CardanoWallet.
+    # @example Initialize CardanoWallet with default settings
+    #  @cw = CardanoWallet.new
+    #
+    # @example Initialize CardanoWallet with custom settings
+    #  @cw = CardanoWallet.new({ port: 4445,
+    #                            protocol: 'https',
+    #                            cacert: '/path/to/cacert',
+    #                            pem: '/path/to/client.pem',
+    #                            timeout: 600 })
     def initialize(opt = {})
       raise ArgumentError, 'argument should be Hash' unless opt.is_a?(Hash)
 

lib/cardano_wallet/byron.rb

@@ -3,13 +3,24 @@
 module CardanoWallet
   ##
   # Byron APIs
+  # @example
+  #  @cw = CardanoWallet.new
+  #  @cw.byron # API for Byron
   module Byron
     def self.new(opt)
       Init.new opt
     end
 
     ##
-    # Init class for Byron APIs
+    # Init class for Byron APIs.
+    # @example
+    #  @cw = CardanoWallet.new
+    #  @cw.byron.wallets # API for Byron wallets
+    #  @cw.byron.assets # API for Byron assets
+    #  @cw.byron.coin_selections # API for Byron coin_selections
+    #  @cw.byron.addresses # API for Byron addresses
+    #  @cw.byron.transactions # API for Byron transactions
+    #  @cw.byron.migrations # API for Byron migrations
     class Init < Base
       # Get API for Byron wallets
       # @see https://input-output-hk.github.io/cardano-wallet/api/edge/#tag/Byron-Wallets
@@ -50,10 +61,15 @@ def assets
 
     ##
     # Init for Byron assets APIs
+    # @example
+    #  @cw = CardanoWallet.new
+    #  @cw.byron.assets # API for Byron assets
     class Assets < Base
       # @see https://input-output-hk.github.io/cardano-wallet/api/edge/#operation/listByronAssets
       # @see https://input-output-hk.github.io/cardano-wallet/api/edge/#operation/getByronAsset
       # @see https://input-output-hk.github.io/cardano-wallet/api/edge/#operation/getByronAssetDefault
+      # @example Get all assets that were ever involved in wallet transaction and been on balance
+      #  @cw.byron.assets.get(wallet_id)
       def get(wid, policy_id = nil, asset_name = nil)
         ep = "/byron-wallets/#{wid}/assets"
         ep += "/#{policy_id}" if policy_id
@@ -64,15 +80,22 @@ def get(wid, policy_id = nil, asset_name = nil)
 
     # Byron wallets
     # @see https://input-output-hk.github.io/cardano-wallet/api/edge/#tag/Byron-Wallets
+    # @example
+    #  @cw = CardanoWallet.new
+    #  @cw.byron.wallets # API for Byron wallets
     class Wallets < Base
       # List Byron wallets
       # @see https://input-output-hk.github.io/cardano-wallet/api/edge/#operation/listByronWallets
+      # @example Get all Byron wallets
+      #  @cw.byron.wallets.get
       def list
         self.class.get('/byron-wallets')
       end
 
       # Get Byron wallet details
       # @see https://input-output-hk.github.io/cardano-wallet/api/edge/#operation/getByronWallet
+      # @example Get Byron wallet details
+      #  @cw.byron.wallets.get(wallet_id)
       def get(wid)
         self.class.get("/byron-wallets/#{wid}")
       end
@@ -95,6 +118,8 @@ def create(params)
 
       # Delete Byron wallet
       # @see https://input-output-hk.github.io/cardano-wallet/api/edge/#operation/deleteByronWallet
+      # @example Delete Byron wallet
+      #  @cw.byron.wallets.delete(wallet_id)
       def delete(wid)
         self.class.delete("/byron-wallets/#{wid}")
       end
@@ -103,7 +128,7 @@ def delete(wid)
       # @see https://input-output-hk.github.io/cardano-wallet/api/edge/#operation/putByronWallet
       #
       # @example
-      #   update_metadata(wid, {name: "New wallet name"})
+      #   @cw.byron.wallets.update_metadata(wid, {name: "New wallet name"})
       def update_metadata(wid, params)
         Utils.verify_param_is_hash!(params)
         self.class.put("/byron-wallets/#{wid}",
@@ -113,11 +138,15 @@ def update_metadata(wid, params)
 
       # See Byron wallet's utxo distribution
       # @see https://input-output-hk.github.io/cardano-wallet/api/edge/#operation/getByronUTxOsStatistics
+      # @example
+      #   @cw.byron.wallets.utxo(wallet_id)
       def utxo(wid)
         self.class.get("/byron-wallets/#{wid}/statistics/utxos")
       end
 
       # @see https://input-output-hk.github.io/cardano-wallet/api/edge/#operation/getByronWalletUtxoSnapshot
+      # @example
+      #   @cw.byron.wallets.utxo_snapshot(wallet_id)
       def utxo_snapshot(wid)
         self.class.get("/byron-wallets/#{wid}/utxo")
       end
@@ -126,7 +155,8 @@ def utxo_snapshot(wid)
       # @see https://input-output-hk.github.io/cardano-wallet/api/edge/#operation/putByronWalletPassphrase
       #
       # @example
-      #   update_passphrase(wid, {old_passphrase: "Secure Passphrase", new_passphrase: "Securer Passphrase"})
+      #   @cw.byron.wallets.update_passphrase(wid, {old_passphrase: "Secure Passphrase",
+      #                                             new_passphrase: "Securer Passphrase"})
       def update_passphrase(wid, params)
         Utils.verify_param_is_hash!(params)
         self.class.put("/byron-wallets/#{wid}/passphrase",
@@ -137,12 +167,15 @@ def update_passphrase(wid, params)
 
     # Byron addresses
     # @see https://input-output-hk.github.io/cardano-wallet/api/edge/#tag/Byron-Addresses
+    # @example
+    #  @cw = CardanoWallet.new
+    #  @cw.byron.addresses # API for Byron addresses
     class Addresses < Base
       # List Byron addresses.
       # @see https://input-output-hk.github.io/cardano-wallet/api/edge/#operation/listByronAddresses
       #
       # @example
-      #   list(wid, {state: "used"})
+      #   @cw.byron.addresses.list(wid, {state: "used"})
       def list(wid, query = {})
         query_formatted = query.empty? ? '' : Utils.to_query(query)
         self.class.get("/byron-wallets/#{wid}/addresses#{query_formatted}")
@@ -154,9 +187,9 @@ def list(wid, query = {})
       # @param params [Hash] passphrase and (optional) address_index
       #
       # @example Create address with index.
-      #   create(wid, {passphrase: "Secure Passphrase", address_index: 2147483648})
+      #   @cw.byron.addresses.create(wid, {passphrase: "Secure Passphrase", address_index: 2147483648})
       # @example Create address with random index.
-      #   create(wid, {passphrase: "Secure Passphrase"})
+      #   @cw.byron.addresses.create(wid, {passphrase: "Secure Passphrase"})
       def create(wid, params)
         Utils.verify_param_is_hash!(params)
         self.class.post("/byron-wallets/#{wid}/addresses",
@@ -185,13 +218,16 @@ def bulk_import(wid, addresses)
 
     # API for CoinSelections
     # @see https://input-output-hk.github.io/cardano-wallet/api/edge/#tag/Byron-Coin-Selections
+    # @example
+    #  @cw = CardanoWallet.new
+    #  @cw.byron.coin_selections # API for Byron coin_selections
     class CoinSelections < Base
       # Show random coin selection for particular payment
       # @see https://input-output-hk.github.io/cardano-wallet/api/edge/#operation/byronSelectCoins
       #
       # @example
-      #   random(wid, [{addr1: 1000000}, {addr2: 1000000}])
-      #   random(wid, [{ "address": "addr1..",
+      #   @cw.byron.coin_selections.random(wid, [{addr1: 1000000}, {addr2: 1000000}])
+      #   @cw.byron.coin_selections.random(wid, [{ "address": "addr1..",
       #                  "amount": { "quantity": 42000000, "unit": "lovelace" },
       #                  "assets": [{"policy_id": "pid", "asset_name": "name", "quantity": 0 } ] } ])
       def random(wid, payments)
@@ -209,6 +245,9 @@ def random(wid, payments)
 
     # Byron transactions
     # @see https://input-output-hk.github.io/cardano-wallet/api/edge/#operation/postByronTransactionFee
+    # @example
+    #  @cw = CardanoWallet.new
+    #  @cw.byron.transactions # API for Byron Transactions
     class Transactions < Base
       # Construct transaction
       # @see https://input-output-hk.github.io/cardano-wallet/api/edge/#operation/constructByronTransaction
@@ -266,7 +305,7 @@ def get(wid, tx_id)
       # @see https://input-output-hk.github.io/cardano-wallet/api/edge/#operation/listByronTransactions
       #
       # @example
-      #   list(wid, {start: "2012-09-25T10:15:00Z", order: "descending"})
+      #   @cw.byron.transactions.list(wid, {start: "2012-09-25T10:15:00Z", order: "descending"})
       def list(wid, query = {})
         query_formatted = query.empty? ? '' : Utils.to_query(query)
         self.class.get("/byron-wallets/#{wid}/transactions#{query_formatted}")
@@ -279,8 +318,8 @@ def list(wid, query = {})
       # @param payments [Array of Hashes] addres, amount pair
       #
       # @example
-      #   create(wid, passphrase, [{addr1: 1000000}, {addr2: 1000000}])
-      #   create(wid, passphrase, [{ "address": "addr1..",
+      #   @cw.byron.transactions.create(wid, passphrase, [{addr1: 1000000}, {addr2: 1000000}])
+      #   @cw.byron.transactions.create(wid, passphrase, [{ "address": "addr1..",
       #                              "amount": { "quantity": 42000000, "unit": "lovelace" },
       #                              "assets": [{"policy_id": "pid", "asset_name": "name", "quantity": 0 } ] } ])
 
@@ -301,8 +340,8 @@ def create(wid, passphrase, payments)
       # @see https://input-output-hk.github.io/cardano-wallet/api/edge/#operation/postTransactionFee
       #
       # @example
-      #   payment_fees(wid, [{addr1: 1000000}, {addr2: 1000000}])
-      #   payment_fees(wid, [{ "address": "addr1..",
+      #   @cw.byron.transactions.payment_fees(wid, [{addr1: 1000000}, {addr2: 1000000}])
+      #   @cw.byron.transactions.payment_fees(wid, [{ "address": "addr1..",
       #                        "amount": { "quantity": 42000000, "unit": "lovelace" },
       #                        "assets": [{"policy_id": "pid", "asset_name": "name", "quantity": 0 } ] } ])
       def payment_fees(wid, payments)
@@ -326,6 +365,9 @@ def forget(wid, txid)
 
     # Byron migrations
     # @see https://input-output-hk.github.io/cardano-wallet/api/edge/#tag/Byron-Migrations
+    # @example
+    #  @cw = CardanoWallet.new
+    #  @cw.byron.migrations # API for Byron Migrations
     class Migrations < Base
       # Get migration plan
       # @see https://input-output-hk.github.io/cardano-wallet/api/edge/#operation/createByronWalletMigrationPlan

lib/cardano_wallet/misc.rb

@@ -2,7 +2,10 @@
 
 module CardanoWallet
   ##
-  # misc
+  # Misc
+  # @example
+  #  @cw = CardanoWallet.new
+  #  @cw.misc
   module Misc
     def self.new(opt)
       Init.new opt
@@ -39,6 +42,9 @@ def node
     end
 
     # @see https://input-output-hk.github.io/cardano-wallet/api/edge/#tag/Node
+    # @example
+    #  @cw = CardanoWallet.new
+    #  @cw.misc.node
     class Node < Base
       # @see https://input-output-hk.github.io/cardano-wallet/api/edge/#tag/Node/paths/~1blocks~1latest~1header/get
       def block_header
@@ -48,6 +54,9 @@ def block_header
 
     # API for Network
     # @see https://input-output-hk.github.io/cardano-wallet/api/edge/#tag/Settings
+    # @example
+    #  @cw = CardanoWallet.new
+    #  @cw.misc.settings
     class Settings < Base
       # @see https://input-output-hk.github.io/cardano-wallet/api/edge/#operation/getSettings
       def get
@@ -65,6 +74,9 @@ def update(params)
 
     # API for Network
     # @see https://input-output-hk.github.io/cardano-wallet/api/edge/#tag/Network
+    # @example
+    #  @cw = CardanoWallet.new
+    #  @cw.misc.network
     class Network < Base
       # Get network information
       # @see https://input-output-hk.github.io/cardano-wallet/api/edge/#operation/getNetworkInformation
@@ -86,6 +98,9 @@ def parameters
     end
 
     # @see https://input-output-hk.github.io/cardano-wallet/api/edge/#tag/Utils
+    # @example
+    #  @cw = CardanoWallet.new
+    #  @cw.misc.utils
     class Utils < Base
       # @see https://input-output-hk.github.io/cardano-wallet/api/#operation/signMetadata
       def sign_metadata(wid, role, index, pass, metadata)
@@ -128,6 +143,9 @@ def smash_health(query = {})
     end
 
     # @see https://input-output-hk.github.io/cardano-wallet/api/edge/#tag/Proxy
+    # @example
+    #  @cw = CardanoWallet.new
+    #  @cw.misc.proxy
     class Proxy < Base
       # Submit a transaction that was created and signed outside of cardano-wallet.
       # @see https://input-output-hk.github.io/cardano-wallet/api/edge/#operation/postExternalTransaction