docs: graph delete

docs/source/graphs.md

@@ -79,6 +79,8 @@ The argument `my-graph@my-variant` in the example above specifies the ID of the
 
 > You can omit `@` and the variant name. If you do, Rover publishes the schema to the default variant, named `current`.
 
+If the graph exists in the graph registry, but the variant does not, a new variant will be created on publish.
+
 ### Providing the schema
 
 You provide your schema to Rover commands via the `--schema` option. The value is usually the path to a local `.graphql` or `.gql` file in [SDL format](https://www.apollographql.com/docs/resources/graphql-glossary/#schema-definition-language-sdl).
@@ -112,3 +114,9 @@ rover graph introspect http://localhost:4000 | rover graph check my-graph --sche
 As shown, arguments and options are similar to [`graph publish`](#publishing-a-schema-to-apollo-studio).
 
 To configure the behavior of schema checks (such as the time range of past operations to check against), see the [documentation for schema checks](https://www.apollographql.com/docs/studio/check-configurations/#using-apollo-studio-recommended).
+
+## Deleting a variant
+
+> This requires first [authenticating Rover with Apollo Studio](./configuring/#authenticating-with-apollo-studio).
+
+You can delete a single variant of a graph by running `rover graph delete`. If this graph is federated, it will also delete all of the subgraphs, meaning any of Rover's `fetch` commands will no longer work with this variant. This command will prompt you for confirmation before deletion since the action is irreversible. You can bypass this confirmation by passing the `--confirm` flag.

docs/source/subgraphs.md

@@ -125,15 +125,17 @@ Use the `subgraph publish` command, like so:
 
 ```bash
 rover subgraph publish my-supergraph@my-variant \
-  --schema ./accounts/schema.graphql\
-  --name accounts\
-  --routing-url https://my-running-subgraph.com/api
+  --schema "./accounts/schema.graphql" \
+  --name accounts \
+  --routing-url "https://my-running-subgraph.com/api"
 ```
 
-The argument `my-graph@my-variant` in the example above is a [graph ref](./conventions/#graph-refs) that specifies the ID of the Studio graph you're publishing to, along with which [variant](https://www.apollographql.com/docs/studio/org/graphs/#managing-variants) you're publishing to.
+The argument `my-supergraph@my-variant` in the example above is a [graph ref](./conventions/#graph-refs) that specifies the ID of the Studio graph you're publishing to, along with which [variant](https://www.apollographql.com/docs/studio/org/graphs/#managing-variants) you're publishing to.
 
 > You can omit `@` and the variant name. If you do, Rover publishes the schema to the default variant, named `current`.
 
+If the graph exists in the graph registry, but the variant does not, a new variant will be created on publish.
+
 Options include:
 
 <table class="field-table">
@@ -188,6 +190,23 @@ The URL that your gateway uses to communicate with the subgraph in a [managed fe
 
 **Optional** after your first publish. Provide only if you need to change the subgraph's routing URL.
 
+</td>
+</tr>
+<tr class="required">
+<td>
+
+###### `--convert`
+
+</td>
+
+<td>
+
+If a monolithic schema for this variant already exists in the graph registry instead of multiple subgraph schemas, you will need to run `rover subgraph publish` with the `--convert` flag in order to convert this variant to be a federated graph with one or more subgraphs. This will _permanently_ delete the existing schema from this variant and replace it with a single subgraph. You will likely need to run multiple `subgraph publish` multiple times in order to successfully compose a supergraph.
+
+**Required** if you are converting an existing monolithic graph variant to a federated graph variant with one or more subgraphs.
+
+**Optional** if the graph variant already has one or more subgraphs.
+
 </td>
 </tr>
 </tbody>
@@ -215,3 +234,7 @@ rover subgraph introspect http://localhost:4000 \
 As shown, arguments and options are similar to [`subgraph publish`](#publishing-a-subgraph-schema-to-apollo-studio).
 
 To configure the behavior of schema checks (such as the time range of past operations to check against), see the [documentation for schema checks](https://www.apollographql.com/docs/studio/check-configurations/#using-apollo-studio-recommended).
+
+## Deleting a subgraph
+
+You can delete a single subgraph by running `rover subgraph delete`. Note that this command will error if any other subgraph references types specified by the subgraph you're deleting. If you'd rather delete all of the subgraphs for a variant, see the docs for [`graph delete`](./graphs/#deleting-a-variant).