Improve setup instructions (#85)

Author: gabrielfeo

README.md

@@ -9,12 +9,16 @@ A Kotlin library to access the [Gradle Enterprise API][1], easy to use from:
 - [Kotlin scripts (`kts`)][27]
 - [Kotlin projects][28]
 
+Using the API is as easy as this:
+
 ```kotlin
 GradleEnterpriseApi.buildsApi.getBuilds(since = yesterdayMilli).forEach {
   println(it)
 }
 ```
 
+ The library takes care of caching under the hood (opt-in) and provides some convenience extensions.
+
 ## Setup
 
 Set up once and use the library from anywhere in your machine:
@@ -23,13 +27,25 @@ Set up once and use the library from anywhere in your machine:
 - [`GRADLE_ENTERPRISE_API_TOKEN`][17] environment variable: an API access token for the Gradle
   Enterprise instance.
   - Or a macOS keychain entry labeled `gradle-enterprise-api-token` (recommended).
+  - <details>
+
+      <summary>How to get an API token</summary>
+
+      The Gradle Enterprise user must have the “Export build data via the API” permission.
+
+      1. Sign in to Gradle Enterprise
+      2. Go to "My settings" from the user menu in the top right-hand corner of the page
+      3. Go to "Access keys" from the sidebar
+      4. Click "Generate" on the right-hand side and copy the generated token.
+
+    </details>
 
-That's it! You can now use the library without any code configuration from notebooks, scripts or 
+That's it! You can now use the library without any code configuration from notebooks, scripts or
 projects.
 
 ### Setup snippets
 
-ℹ️ The library is now published to Maven Central under `com.gabrielfeo`. Maven Central is 
+ℹ️ The library is now published to Maven Central under `com.gabrielfeo`. Maven Central is
 recommended over JitPack.
 
 <details>

examples/build.gradle.kts

@@ -7,7 +7,7 @@ exampleTestTasks += tasks.register<Exec>("runExampleScript") {
 }
 
 exampleTestTasks += tasks.register<GradleBuild>("runExampleProject") {
-    group = "Verification"
+    group = "Application"
     description = "Runs examples/example-project as a standalone build"
     dir = file("example-project")
     tasks = listOf("run")
@@ -32,7 +32,7 @@ exampleTestTasks += notebooks.map { notebook ->
     }
 }
 
-tasks.register("runExamples") {
+tasks.register("runAll") {
     group = "Application"
     description = "Runs everything in 'examples' directory"
     dependsOn(exampleTestTasks)

examples/example-notebooks/MostFrequentBuilds.ipynb

@@ -25,25 +25,27 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "79661abe-8aea-48c2-9938-e9452c0161d0",
    "metadata": {},
    "source": [
     "## Setup\n",
     "\n",
-    "`%use` is a [line magic](https://github.com/Kotlin/kotlin-jupyter#line-magics) of the Kotlin kernel that can do much more than adding the library. To illustrate, this setup:\n",
+    "Add libraries to use, via line magics. `%use` is a [line magic](https://github.com/Kotlin/kotlin-jupyter#line-magics) of the Kotlin kernel that can do much more than adding the library. To illustrate, this setup can be replaced with a single line magic.\n",
     "\n",
     "```kotlin\n",
     "@file:DependsOn(\"com.gabrielfeo:gradle-enterprise-api-kotlin:0.16.2\")\n",
     "\n",
     "import com.gabrielfeo.gradle.enterprise.api.*\n",
     "import com.gabrielfeo.gradle.enterprise.api.model.*\n",
+    "import com.gabrielfeo.gradle.enterprise.api.extension.*\n",
     "```\n",
     "\n",
-    "can be entirely replaced by:\n",
+    "is the same as:\n",
     "\n",
     "```\n",
-    "%use gradle-enterprise-api-kotlin\n",
+    "%use gradle-enterprise-api-kotlin(version=0.16.2)\n",
     "```"
    ]
   },