From 47769e9fff46e9498aebacdafb6bf31ed5410e69 Mon Sep 17 00:00:00 2001
From: Devon Stewart <blast@hardchee.se>
Date: Mon, 21 Jun 2021 12:28:39 -0700
Subject: [PATCH] Documenting URL generation

---
 vuepress/docs/docs/client.md | 19 ++++++++++++++++++-
 vuepress/docs/docs/schema.md | 20 ++++++++++++++++++--
 2 files changed, 36 insertions(+), 3 deletions(-)

diff --git a/vuepress/docs/docs/client.md b/vuepress/docs/docs/client.md
index d6ca48f49..9f0a97aff 100644
--- a/vuepress/docs/docs/client.md
+++ b/vuepress/docs/docs/client.md
@@ -35,6 +35,8 @@ And enable it in your `build.sbt` file:
 enablePlugins(CalibanPlugin)
 ```
 
+### File generation
+
 At this point, the `caliban` command will cause any files in `src/main/graphql` to be translated into a Caliban-generated client library. This happens automatically any time you `compile`.
 
 By default, all clients are generated with the same client name as the source file, in the `caliban` top-level package.
@@ -57,15 +59,30 @@ In order to supply more configuration options to the code generator, you can use
       )
 ```
 
+### URL generation
+
+The `calibanSetting` function also permits generating clients for supplied `url`'s:
+```scala
+      Compile / caliban / calibanSettings += calibanSetting(url("http://my-example-service/graphql"))(
+        cs =>
+          cs.clientName("ExampleServiceClient")
+            .packageName("com.example.graphql.client")
+      )
+```
+
+### `calibanSetting` config parameters
+
 The settings available on the `cs` (`CalibanSettings`) builder are:
 ```
   def scalafmtPath(path: String): CalibanSettings
-  def headers(pairs: (String,String)*): CalibanSettings
   def packageName(name: String): CalibanSettings
   def genView(value: Boolean): CalibanSettings
   def effect(tpe: String): CalibanSettings
   def scalarMapping(mapping: (String,String)*): CalibanSettings
   def imports(values: String*): CalibanSettings
+
+  // Only defined for `url` settings, for use in supplying extra headers when fetching the schema itself
+  def headers(pairs: (String,String)*): CalibanSettings
 ```
 
 ### `calibanGenClient`
diff --git a/vuepress/docs/docs/schema.md b/vuepress/docs/docs/schema.md
index dcd2b09ac..640309a60 100644
--- a/vuepress/docs/docs/schema.md
+++ b/vuepress/docs/docs/schema.md
@@ -230,6 +230,8 @@ And enable it in your `build.sbt` file:
 enablePlugins(CalibanPlugin)
 ```
 
+### File generation
+
 At this point, the `caliban` command will cause any files in `src/main/graphql` to be translated into a Caliban-generated client library. This happens automatically any time you `compile`.
 
 By default, all clients are generated with the same client name as the source file, in the `caliban` top-level package.
@@ -252,17 +254,31 @@ In order to supply more configuration options to the code generator, you can use
       )
 ```
 
+### URL generation
+
+The `calibanSetting` function also permits generating clients for supplied `url`'s:
+```scala
+      Compile / caliban / calibanSettings += calibanSetting(url("http://my-example-service/graphql"))(
+        cs =>
+          cs.clientName("ExampleServiceClient")
+            .packageName("com.example.graphql.client")
+      )
+```
+
+### `calibanSetting` config parameters
+
 The settings available on the `cs` (`CalibanSettings`) builder are:
 ```
   def scalafmtPath(path: String): CalibanSettings
-  def headers(pairs: (String,String)*): CalibanSettings
   def packageName(name: String): CalibanSettings
   def genView(value: Boolean): CalibanSettings
   def effect(tpe: String): CalibanSettings
   def scalarMapping(mapping: (String,String)*): CalibanSettings
   def imports(values: String*): CalibanSettings
-```
 
+  // Only defined for `url` settings, for use in supplying extra headers when fetching the schema itself
+  def headers(pairs: (String,String)*): CalibanSettings
+```
 
 ## Building Schemas by hand