From 906a0b899e3f417e9e0b2575f038f19ac4a355ab Mon Sep 17 00:00:00 2001
From: Varun Gandhi <varun.gandhi@sourcegraph.com>
Date: Wed, 2 Nov 2022 13:24:00 +0800
Subject: [PATCH] docs: Add docs for CLI and building from source.

---
 README.md                      | 12 ++++++++++--
 docs/scip-ruby/CLI.md          | 30 ++++++++++++++++++++++++++++++
 docs/scip-ruby/CONTRIBUTING.md |  1 +
 3 files changed, 41 insertions(+), 2 deletions(-)
 create mode 100644 docs/scip-ruby/CLI.md

diff --git a/README.md b/README.md
index 1e2938bbc..23205d418 100644
--- a/README.md
+++ b/README.md
@@ -65,8 +65,10 @@ Run `scip-ruby` along with some information about your gem.
     bundle exec scip-ruby .
     ```
 
-These commands will output a SCIP index to `index.scip` (overridable via `--index-file`).
-The gem name and version will be inferred from config files (overridable via `--gem-metadata`).
+These commands will output a SCIP index to `index.scip`.
+Any other needed information will be inferred from directory layout.
+For customizing how `scip-ruby` interprets your configuration,
+see the [CLI reference](docs/scip-ruby/CLI.md).
 
 The SCIP index can be uploaded to a Sourcegraph instance
 using the [Sourcegraph CLI](https://github.com/sourcegraph/src-cli)'s
@@ -102,6 +104,12 @@ SRC_ACCESS_TOKEN="your token" SRC_ENDPOINT="url for Sourcegraph instance" src co
 
 For more details, see the Sourcegraph CLI docs.
 
+## Building from source for indexing
+
+See the [Contributing docs](./docs/scip-ruby/CONTRIBUTING.md)
+for build instructions.
+Once the `scip-ruby` binary is built, you can index it as described above.
+
 ## Contributing
 
 See the [Contributing docs](./docs/scip-ruby/CONTRIBUTING.md).
diff --git a/docs/scip-ruby/CLI.md b/docs/scip-ruby/CLI.md
new file mode 100644
index 000000000..bb9a05139
--- /dev/null
+++ b/docs/scip-ruby/CLI.md
@@ -0,0 +1,30 @@
+# scip-ruby CLI
+
+This document describes scip-ruby specific flags.
+
+## `--gem-metadata <arg>`
+
+The argument should be `name@version` format, which identifies the current
+repository for cross-repo code navigation. By default, `scip-ruby` will
+attempt to infer the name and version by looking at `Gemfile.lock`,
+any available `.gemspec` files and, both of those failing, the current directory
+name (for the version).
+
+If you don't have any of these files, or the information is specified
+dynamically (since arbitrary Ruby code is allowed in `.gemspec` files),
+you can supply this argument explicitly instead.
+
+The version should generally correspond to the previously released version.
+For example, with Git, you can use the last tag
+(`git describe --tags --abbrev=0`). However, the version can be an arbitrary
+string. For repos which index every commit, you could also use the SHA
+instead (`git rev-parse HEAD`).
+
+## `--unquiet-errors`
+
+scip-ruby defaults to running in Sorbet's quiet mode, as scip-ruby supports
+indexing `# typed: false` files on a best-effort basis, but Sorbet may
+rightfully flag many errors in those files. The number of errors can be
+overwhelming if there is a large amount of untyped code.
+
+This flag restores Sorbet's default behavior.
diff --git a/docs/scip-ruby/CONTRIBUTING.md b/docs/scip-ruby/CONTRIBUTING.md
index a951d4191..842aa592d 100644
--- a/docs/scip-ruby/CONTRIBUTING.md
+++ b/docs/scip-ruby/CONTRIBUTING.md
@@ -108,6 +108,7 @@ see the [Design Decisions doc][].
 ## Building
 
 ```
+# Optionally replace 'dbg' with 'release-linux' or 'release-mac'
 ./bazel build //main:scip-ruby --config=dbg
 ```