|
| 1 | +## Setting up the environment |
| 2 | + |
| 3 | +This repository contains a `.ruby-version` file, which should work with either [rbenv](https://github.com/rbenv/rbenv) or [asdf](https://github.com/asdf-vm/asdf) with the [ruby plugin](https://github.com/asdf-vm/asdf-ruby). |
| 4 | + |
| 5 | +Please follow the instructions for your preferred version manager to install the Ruby version specified in the `.ruby-version` file. |
| 6 | + |
| 7 | +To set up the repository, run: |
| 8 | + |
| 9 | +```bash |
| 10 | +$ ./scripts/bootstrap |
| 11 | +``` |
| 12 | + |
| 13 | +This will install all the required dependencies. |
| 14 | + |
| 15 | +## Modifying/Adding code |
| 16 | + |
| 17 | +Most of the SDK is generated code. Modifications to code will be persisted between generations, but may result in merge conflicts between manual patches and changes from the generator. The generator will never modify the contents of `lib/finch_api/helpers/` and `examples/` directory. |
| 18 | + |
| 19 | +## Adding and running examples |
| 20 | + |
| 21 | +All files in the `examples/` directory are not modified by the generator and can be freely edited or added to. |
| 22 | + |
| 23 | +```ruby |
| 24 | +#!/usr/bin/env ruby |
| 25 | +# frozen_string_literal: true |
| 26 | + |
| 27 | +require_relative "../lib/finch_api" |
| 28 | + |
| 29 | +# ... |
| 30 | +``` |
| 31 | + |
| 32 | +```bash |
| 33 | +$ chmod +x './examples/<your-example>.rb' |
| 34 | + |
| 35 | +# run the example against your api |
| 36 | +$ ruby './examples/<your-example>.rb' |
| 37 | +``` |
| 38 | + |
| 39 | +## Using the repository from source |
| 40 | + |
| 41 | +If you’d like to use the repository from source, you can either install from git or reference a cloned repository: |
| 42 | + |
| 43 | +To install via git in your `Gemfile`: |
| 44 | + |
| 45 | +```ruby |
| 46 | +gem "finch-api", git: "https://www.github.com/Finch-API/finch-api-ruby" |
| 47 | +``` |
| 48 | + |
| 49 | +Alternatively, reference local copy of the repo: |
| 50 | + |
| 51 | +```bash |
| 52 | +$ git clone -- 'https://www.github.com/Finch-API/finch-api-ruby' '<path-to-repo>' |
| 53 | +``` |
| 54 | + |
| 55 | +```ruby |
| 56 | +gem "finch-api", path: "<path-to-repo>" |
| 57 | +``` |
| 58 | + |
| 59 | +## Running commands |
| 60 | + |
| 61 | +Running `rake` by itself will show all runnable commands. |
| 62 | + |
| 63 | +```bash |
| 64 | +$ bundle exec rake |
| 65 | +``` |
| 66 | + |
| 67 | +## Running tests |
| 68 | + |
| 69 | +Most tests require you to [set up a mock server](https://github.com/stoplightio/prism) against the OpenAPI spec to run the tests. |
| 70 | + |
| 71 | +```bash |
| 72 | +$ npx prism mock path/to/your/openapi.yml |
| 73 | +``` |
| 74 | + |
| 75 | +```bash |
| 76 | +$ bundle exec rake test |
| 77 | +``` |
| 78 | + |
| 79 | +## Linting and formatting |
| 80 | + |
| 81 | +This repository uses [rubocop](https://github.com/rubocop/rubocop) for linting and formatting of `*.rb` and `*.rbi` files. [syntax_tree](https://github.com/ruby-syntax-tree/syntax_tree) is used for formatting `*.rbs` files. |
| 82 | + |
| 83 | +There are two separate type checkers supported by this library: [sorbet](https://github.com/sorbet/sorbet) and [steep](https://github.com/soutaro/steep) are used for verifying `*.rbi` and `*.rbs` files respectively. |
| 84 | + |
| 85 | +To lint and typecheck: |
| 86 | + |
| 87 | +```bash |
| 88 | +$ bundle exec rake lint |
| 89 | +``` |
| 90 | + |
| 91 | +To format and fix all lint issues automatically: |
| 92 | + |
| 93 | +```bash |
| 94 | +$ bundle exec rake format |
| 95 | +``` |
| 96 | + |
| 97 | +## Editor Support |
| 98 | + |
| 99 | +### Ruby LSP |
| 100 | + |
| 101 | +[Ruby LSP](https://github.com/Shopify/ruby-lsp) has quite good support for go to definition, but not auto-completion. |
| 102 | + |
| 103 | +This can be installed along side Solargraph. |
| 104 | + |
| 105 | +### Solargraph |
| 106 | + |
| 107 | +[Solargraph](https://solargraph.org) has quite good support for auto-completion, but not go to definition. |
| 108 | + |
| 109 | +This can be installed along side Ruby LSP. |
| 110 | + |
| 111 | +### Sorbet |
| 112 | + |
| 113 | +[Sorbet](https://sorbet.org) should mostly work out of the box when editing this library directly. However, there are a some caveats due to the colocation of `*.rb` and `*.rbi` files in the same project. These issues should not otherwise manifest when this library is used as a dependency. |
| 114 | + |
| 115 | +1. For go to definition usages, sorbet might get confused and may not always navigate to the correct location. |
| 116 | + |
| 117 | +2. For each generic type in `*.rbi` files, a spurious "Duplicate type member" error is present. |
| 118 | + |
| 119 | +## Documentation Preview |
| 120 | + |
| 121 | +To preview the documentation, run: |
| 122 | + |
| 123 | +```bash |
| 124 | +$ bundle exec rake docs:preview [PORT=8808] |
| 125 | +``` |
![stainless-app[bot]](https://avatars.githubusercontent.com/in/378072?v=4&size=40){kind=avatar}
0 commit comments