Add a AS/IJ plugin doc

docs/source/config.json

@@ -61,7 +61,8 @@
       "Batching operations": "/advanced/query-batching"
     },
     "Development & Testing": {
-      "Overview": "/testing/overview",
+      "Android Studio plugin": "/testing/android-studio-plugin",
+      "Testing overview": "/testing/overview",
       "Mocking HTTP responses": "/testing/mocking-http-responses",
       "Mocking GraphQL responses": "/testing/mocking-graphql-responses",
       "Data builders": "/testing/data-builders",

docs/source/index.md

@@ -154,7 +154,7 @@ As the code generated by Apollo Kotlin doesn't use any reflection, it can safely
 
 An experimental [plugin for Android Studio and IntelliJ](https://plugins.jetbrains.com/plugin/20645-apollo-graphql) is available to help you work with Apollo Kotlin, providing automatic code generation, integration with the [GraphQL IntelliJ Plugin](https://plugins.jetbrains.com/plugin/8097-js-graphql), navigation to GraphQL definitions, migration helpers, and more.
 
-Installation instructions and more information can be found [here](https://github.com/apollographql/apollo-kotlin/tree/main/intellij-plugin).
+Installation instructions and more information can be found [here](testing/android-studio-plugin).
 
 ## Releases
 

docs/source/testing/android-studio-plugin.mdx

@@ -0,0 +1,95 @@
+---
+title: Android Studio / IntelliJ plugin
+---
+
+To help your day-to-day development with Apollo Kotlin, a plugin for Android Studio and IntelliJ is available.
+
+## Installation
+
+The plugin is available on the JetBrains plugin repository. To install it from the IDE, go to
+<kbd>Settings</kbd> | <kbd>Plugins</kbd> | <kbd>Marketplace</kbd> | search for "Apollo GraphQL" | <kbd>Install</kbd>
+
+At the time of writing, the plugin is supported on:
+
+- IntelliJ 2022.2 and above
+- Android Studio 2022.2 (Flamingo) and above
+
+Please check the [plugin page](https://plugins.jetbrains.com/plugin/20645-apollo-graphql) for up to date information.
+
+## Features
+
+### Automatic code generation
+<img src="images/ij-plugin-on-the-fly-codegen.webp" alt="Automatic code generation"/>
+
+The plugin automatically generates models whenever GraphQL files change.
+This means you don't need to manually run `./gradlew generateApolloSources` after editing the files.
+
+Note: this works by running Gradle in continuous mode, and can be disabled in the plugin settings.
+
+### Integration with the GraphQL IntelliJ Plugin
+
+The plugin depends on and integrates with the [GraphQL IntelliJ Plugin](https://plugins.jetbrains.com/plugin/8097-js-graphql).
+The file structure of the Apollo project is automatically contributed, so there is no need to create a `graphql.config.yml` / `.graphqlconfig` file.
+
+### Navigation
+
+#### Kotlin → GraphQL
+
+When editing Kotlin code, <img src="images/gutter-icon.png" alt="Gutter icon" width="16" valign="middle" style="display: inline; margin: 2px;"/> icons will show next to references to generated operation and fragment classes.
+Clicking on them will navigate to the corresponding GraphQL definition.
+
+You can also go to the GraphQL definition with <kbd>Cmd</kbd> Click (Mac) or <kbd>Ctrl</kbd> Click (Windows / Linux) on an operation, field, enum, etc.
+
+<img src="images/ij-plugin-go-to-declaration.webp" alt="Go to declaration"/>
+
+Going to a field's **type** declaration (<kbd>Cmd</kbd> <kbd>Shift</kbd> Click on Mac, <kbd>Ctrl</kbd> <kbd>Shift</kbd> Click on Windows / Linux) will navigate to its definition in the GraphQL schema. 
+
+<img src="images/ij-plugin-go-to-type-declaration.webp" alt="Go to type declaration"/>
+
+#### GraphQL → Kotlin
+
+You can search for code usages of a GraphQL operation, fragment, enum type/value and input type/field, with right click | <kbd>Find Usages</kbd>.
+
+<img src="images/ij-plugin-find-usages.webp" alt="Find usages"/>
+
+### Unused operations / fields
+
+In GraphQL files, operations and fields are shown in grey if the corresponding generated code is not used in your project.
+
+### Migration helpers
+
+In the <kbd>Refactor</kbd> | <kbd>Apollo</kbd> menu, you can find helpers to migrate your project:
+
+- Apollo Android 2.x → Apollo Kotlin 3.x
+- `compat` codegen → `operationBased` codegen
+- Apollo Kotlin 3.x → Apollo Kotlin 4.x
+
+Note: while these helpers will automatically update your code when possible, there are some cases where this isn't possible and manual changes are required.
+Please refer to the migration guides ([3.x](../migration/3.0/), [4.x](../migration/4.0/)) when upgrading.
+
+### Open in Apollo Sandbox
+
+You can open a GraphQL file in [Apollo Sandbox](https://studio.apollographql.com/sandbox/explorer) with right click | <kbd>Open in</kbd> | <kbd>Apollo Sandbox</kbd>.
+This is a handy way to share operations with coworkers for instance. There, they will be able to execute the operation and see the result.
+
+This is also accessible from the <img src="images/open-in-sandbox.png" alt="Sandbox icon" width="16" valign="middle" style="display: inline; margin: 2px;"/> button at the top of the editor.
+
+### High latency fields
+
+If your project uses Apollo GraphOS, the plugin can use the collected metrics (["Field Insights"](https://www.apollographql.com/docs/graphos/metrics/field-usage)) and report a warning on fields that have a high latency.
+
+<img src="images/high-latency-field-editor.png" width="400" alt="High latency in editor"/>
+
+By default, fields with a latency above 100ms will be highlighted. You can change this threshold in <kbd>Settings</kbd> | <kbd>Editor</kbd> | <kbd>Inspections</kbd> | <kbd>GraphQL</kbd> | <kbd>Apollo GraphOS</kbd> | <kbd>High latency field</kbd>.
+
+A quick fix is available to encapsulate the field in a fragment with the [`@defer`](../fetching/defer) directive.
+
+For the plugin to be able to fetch the metrics, you need to configure your project with its [Apollo GraphOS API key](https://www.apollographql.com/docs/graphos/api-keys/). To do this, go to the plugin's settings: <kbd>Settings</kbd> | <kbd>Languages & Frameworks</kbd> | <kbd>GraphQL</kbd> | <kbd>Apollo Kotlin</kbd>. Here you can find the <kbd>API keys</kbd> table where you can add:
+- API key: should start with `service:` or `user:`
+- Graph ID: can be found on your graph page in Apollo Studio or is filled automatically if you provide a `service:` API key
+
+## Weekly snapshots
+
+If you wish to try the latest features, you can install the weekly snapshots. To do so, add the following repository in <kbd>Settings</kbd> | <kbd>Plugins</kbd> | <kbd>⚙</kbd>️ | <kbd>Manage Plugin Repositories</kbd> | <kbd>+</kbd>: `https://raw.githubusercontent.com/apollographql/apollo-kotlin/main/intellij-plugin/snapshots/plugins.xml`.
+
+Then installing the plugin by searching "Apollo GraphQL" in the Marketplace will install the latest snapshot.

intellij-plugin/gradle.properties

@@ -6,7 +6,7 @@ pluginId=com.apollographql.ijplugin
 pluginRepositoryUrl=https://github.com/apollographql/apollo-kotlin
 
 
-# XXX Do update the supported versions in the README.md file when updating these values!
+# XXX Do update the supported versions in the README.md, and in docs/source/testing/android-studio-plugin.mdx file when updating these values!
 # See https://plugins.jetbrains.com/docs/intellij/build-number-ranges.html
 # for insight into build numbers and IntelliJ Platform versions.
 pluginSinceBuild=222