From 7871b8d71bdd7d6848583f201f7b60bdf5459499 Mon Sep 17 00:00:00 2001 From: Christine Yu Date: Tue, 7 Jun 2022 07:59:43 -0700 Subject: [PATCH 1/3] add documention for the rover readme commands --- docs/source/config.json | 5 ++-- docs/source/readmes.md | 59 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 62 insertions(+), 2 deletions(-) create mode 100644 docs/source/readmes.md diff --git a/docs/source/config.json b/docs/source/config.json index 790f51b67..0e24666f9 100644 --- a/docs/source/config.json +++ b/docs/source/config.json @@ -18,7 +18,8 @@ "Contributing": "/contributing", "Migrating from the Apollo CLI": "/migration", "Base Commands": { - "graph": "/graphs" + "graph": "/graphs", + "readme": "/readmes" }, "Federation Commands": { "subgraph": "/subgraphs", @@ -28,4 +29,4 @@ "Error codes": "/errors" } } -} \ No newline at end of file +} diff --git a/docs/source/readmes.md b/docs/source/readmes.md new file mode 100644 index 000000000..69b007a3c --- /dev/null +++ b/docs/source/readmes.md @@ -0,0 +1,59 @@ +--- +title: Rover README commands +description: Publish and retrieve your graph variant's README +--- + +These Rover commands are for publishing and fetching the [README](https://www.apollographql.com/docs/studio/org/graphs/#the-readme-page) associated with a graph variant. + +READMEs are [Markdown based](https://www.apollographql.com/docs/studio/org/graphs/#supported-markdown), and supports Apollo-specific shortcodes, which are documented [here](https://www.apollographql.com/docs/studio/org/graphs/#readme-shortcodes). + +## Fetching a README from Apollo Studio + +> This requires first [authenticating Rover with Apollo Studio](./configuring/#authenticating-with-apollo-studio). + +You can use Rover to fetch the READE of any Studio graph variant. Run the `readme fetch` comand, like so: + +```bash +rover readme fetch my-graph@my-variant +``` + +The argument `my-graph@my-variant` is the `graph ref`, which you can read about [here](http://localhost:8000/rover/conventions#graph-refs). + +### Output format + +By default, the README will be output to `stdout`. You can also save the output to a `.md` file like so: + +```bash +# Creates README.md or overwrites if it already exists +rover readme fetch my-graph@my-variant > README.md +``` + +To request the output as JSON, use the `--output json` option: +```bash +rover readme fetch my-graph@my-variant +``` + +> For more on passing values via `stdout`, see [Conventions](./conventions#using-stdout). + +## Publishing a README to Apollo Studio + +> This requires first [authenticating Rover with Apollo Studio](./configuring/#authenticating-with-apollo-studio). + +You can use Rover to publish a README to one of your [Apollo Studio graphs](/studio/org/graphs/). + +Use the `readme publish` command: + +```bash +rover readme publish my-graph@my-variant --file ./README.md +``` + +The argument `my-graph@my-variant` is the `graph ref`, which you can read about [here](http://localhost:8000/rover/conventions#graph-refs). + +You can also pipe the contents of the README in via `stdin` by providing `-` as the value of the `--file` option, like so: + +```bash +echo "sample readme contents" | rover readme publish my-graph@my-variant --file - +``` + +> For more on accepting input via `stdin`, see [Conventions](./conventions#using-stdin). + From 8cf0d7506abe2925d49d59a7b9c01b86ab3d4423 Mon Sep 17 00:00:00 2001 From: Christine Date: Tue, 7 Jun 2022 09:28:41 -0700 Subject: [PATCH 2/3] Wording changes Co-authored-by: Avery Harnish --- docs/source/readmes.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/source/readmes.md b/docs/source/readmes.md index 69b007a3c..9fff607a8 100644 --- a/docs/source/readmes.md +++ b/docs/source/readmes.md @@ -5,13 +5,15 @@ description: Publish and retrieve your graph variant's README These Rover commands are for publishing and fetching the [README](https://www.apollographql.com/docs/studio/org/graphs/#the-readme-page) associated with a graph variant. -READMEs are [Markdown based](https://www.apollographql.com/docs/studio/org/graphs/#supported-markdown), and supports Apollo-specific shortcodes, which are documented [here](https://www.apollographql.com/docs/studio/org/graphs/#readme-shortcodes). +READMEs are [Markdown based](https://www.apollographql.com/docs/studio/org/graphs/#supported-markdown), and support Apollo-specific shortcodes, which are documented [here](https://www.apollographql.com/docs/studio/org/graphs/#readme-shortcodes). ## Fetching a README from Apollo Studio > This requires first [authenticating Rover with Apollo Studio](./configuring/#authenticating-with-apollo-studio). -You can use Rover to fetch the READE of any Studio graph variant. Run the `readme fetch` comand, like so: +You can use Rover to fetch the README of any Studio graph variant. + +Run the `readme fetch` command, like so: ```bash rover readme fetch my-graph@my-variant @@ -30,7 +32,7 @@ rover readme fetch my-graph@my-variant > README.md To request the output as JSON, use the `--output json` option: ```bash -rover readme fetch my-graph@my-variant +rover readme fetch my-graph@my-variant --output json ``` > For more on passing values via `stdout`, see [Conventions](./conventions#using-stdout). @@ -41,7 +43,7 @@ rover readme fetch my-graph@my-variant You can use Rover to publish a README to one of your [Apollo Studio graphs](/studio/org/graphs/). -Use the `readme publish` command: +Use the `readme publish` command, like so: ```bash rover readme publish my-graph@my-variant --file ./README.md From ad3aea98bdf38d1af3260ad417f9640e1678f394 Mon Sep 17 00:00:00 2001 From: Christine Date: Tue, 7 Jun 2022 13:38:49 -0700 Subject: [PATCH 3/3] Apply @StephenBarlow's changes Co-authored-by: Stephen Barlow --- docs/source/readmes.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/docs/source/readmes.md b/docs/source/readmes.md index 9fff607a8..e96f8de1b 100644 --- a/docs/source/readmes.md +++ b/docs/source/readmes.md @@ -3,15 +3,15 @@ title: Rover README commands description: Publish and retrieve your graph variant's README --- -These Rover commands are for publishing and fetching the [README](https://www.apollographql.com/docs/studio/org/graphs/#the-readme-page) associated with a graph variant. +These Rover commands enable you to publish and fetch the [README](/studio/org/graphs/#the-readme-page) associated with a particular graph variant. -READMEs are [Markdown based](https://www.apollographql.com/docs/studio/org/graphs/#supported-markdown), and support Apollo-specific shortcodes, which are documented [here](https://www.apollographql.com/docs/studio/org/graphs/#readme-shortcodes). +READMEs are [Markdown-based](/studio/org/graphs/#supported-markdown) and support Apollo-specific shortcodes, which are documented [here](/studio/org/graphs/#readme-shortcodes). ## Fetching a README from Apollo Studio > This requires first [authenticating Rover with Apollo Studio](./configuring/#authenticating-with-apollo-studio). -You can use Rover to fetch the README of any Studio graph variant. +You can use Rover to fetch the README of any Studio graph variant you have access to. Run the `readme fetch` command, like so: @@ -19,18 +19,19 @@ Run the `readme fetch` command, like so: rover readme fetch my-graph@my-variant ``` -The argument `my-graph@my-variant` is the `graph ref`, which you can read about [here](http://localhost:8000/rover/conventions#graph-refs). +The argument `my-graph@my-variant` is the `graph ref`, which you can read about [here](./conventions#graph-refs). ### Output format -By default, the README will be output to `stdout`. You can also save the output to a `.md` file like so: +By default, the README is output to `stdout`. You can also save the output to a `.md` file like so: ```bash # Creates README.md or overwrites if it already exists rover readme fetch my-graph@my-variant > README.md ``` -To request the output as JSON, use the `--output json` option: +You can also request the output as JSON with the `--output json` option: + ```bash rover readme fetch my-graph@my-variant --output json ``` @@ -49,9 +50,9 @@ Use the `readme publish` command, like so: rover readme publish my-graph@my-variant --file ./README.md ``` -The argument `my-graph@my-variant` is the `graph ref`, which you can read about [here](http://localhost:8000/rover/conventions#graph-refs). +The argument `my-graph@my-variant` is the `graph ref`, which you can read about [here](./conventions#graph-refs). -You can also pipe the contents of the README in via `stdin` by providing `-` as the value of the `--file` option, like so: +You can also pipe in the README's contents via `stdin` by providing `-` as the value of the `--file` option, like so: ```bash echo "sample readme contents" | rover readme publish my-graph@my-variant --file -