[EDGE-1520] Add pipeline templates rest & graphql api documentation #2479

jonathanly · 2023-09-18T09:27:18Z

Adds pipeline templates REST API and GraphQL documentation for the following PRs:

Note: graphql doc updates include bits around organization system banners, it's a side effect of generating the documentation via a schema file. I imagine this will resolve in the diff when #2486 is merged. Fixed conflicts via a rebase ✨

buildkite-docs-bot · 2023-09-18T09:27:45Z

Preview URL: https://2479--bk-docs-preview.netlify.app

mhaylock

@jonathanly I've not reviewed everything line by line, but I've reviewed the Preview URL and raised a few things that stand out to me.

PS: It seems that the diff did not clean up after #2486 was merged for some reason - maybe a rebase onto main to fix the merge conflicts will fix it?

pages/apis/rest_api/pipeline_templates.md

jonathanly · 2023-10-02T23:17:44Z

scripts/graphql_api_content/nav_data.rb

Also sorted the index list in alphabetical order here

I'll leave it to the docs team to comment on whether this re-ordering is desirable or not.

data/graphql/schema.graphql

mhaylock

@jonathanly wording for pipeline templates looks good to me, but I think we should exclude all changes relating to build retention.

There is also one syntax error to clean up, and I think the re-ordering of the GraphQL API nav should be run by the docs team.

data/graphql/schema.graphql

pages/apis/graphql/cookbooks/pipeline_templates.md

pages/apis/graphql/schemas/input_object/pipelinecreateinput.md

pages/apis/graphql/schemas/input_object/pipelineupdateinput.md

pages/apis/rest_api/pipeline_templates.md

mhaylock · 2023-10-03T01:33:32Z

scripts/graphql_api_content/nav_data.rb

I'll leave it to the docs team to comment on whether this re-ordering is desirable or not.

mhaylock

Looks good to me! Again I'll leave it to the docs reviewers to make a call on the re-ordering, but the rest of the content looks a-ok to me.

mhaylock · 2023-10-03T21:11:58Z

pages/apis/rest_api/agents.md

@@ -15,7 +15,7 @@ curl "https://api.buildkite.com/v2/organizations/{org.slug}/agents"
    "id": "0b461f65-e7be-4c80-888a-ef11d81fd971",
    "graphql_id": "QWdlbnQtLS1mOTBhNzliNC01YjJlLTQzNzEtYjYxZS03OTA4ZDAyNmUyN2E=",
    "url": "https://api.buildkite.com/v2/organizations/my-great-org/agents/my-agent",
-    "web_url": "https://buildkite.com/organizations/buildkite/my-great-org/agents/0b461f65-e7be-4c80-888a-ef11d81fd971",
+    "web_url": "https://buildkite.com/organizations/my-great-org/agents/0b461f65-e7be-4c80-888a-ef11d81fd971",


Nice clean up of these doubled-up org names! 🎉

mbelton-buildkite

I've left quite a few comments, but nothing major. 😊

pages/apis/rest_api/pipeline_templates.md

mbelton-buildkite · 2023-10-04T01:52:31Z

pages/apis/graphql/graphql_cookbook.md

@@ -13,5 +13,6 @@ There are recipes for a range of different topics, including:
 - [Jobs](/docs/apis/graphql/cookbooks/jobs)
 - [Agents](/docs/apis/graphql/cookbooks/agents)
 - [Clusters](/docs/apis/graphql/cookbooks/clusters)
+- [Pipeline templates](/docs/apis/graphql/cookbooks/pipeline-templates)


Let's match the order used in the navigation:

- [Agents](/docs/apis/graphql/cookbooks/agents) - [Builds](/docs/apis/graphql/cookbooks/builds) - [Clusters](/docs/apis/graphql/cookbooks/clusters) - [Jobs](/docs/apis/graphql/cookbooks/jobs) - [Pipelines](/docs/apis/graphql/cookbooks/pipelines) - [Pipeline templates](/docs/apis/graphql/cookbooks/pipeline-templates) - [Organizations](/docs/apis/graphql/cookbooks/organizations) - [Teams](/docs/apis/graphql/cookbooks/teams)

(I think I saw the start of a conversation somewhere about the ordering of these pages, but I can't find it now. There were reasons they weren't in alphabetic order, but I think it's fine to switch to that given how many pages we have now)

Great pick up @mbelton-buildkite, I lost track of which pages are automatically generated vs which ones aren't 😅.
That convo I had with Chris mentioned whether or not we should alphabetically sort links under the Pipelines REST API:

Do you have opinions on this?

Ahhh okay. Yeah, for reference docs with that many entries, I think moving to order alphabetically is a good idea 😊

I think I have a feature request somewhere to generate index sections like that on Overview pages, so one day it hopefully won't be manual!

Thanks your for input @mbelton-buildkite, I'll go ahead and order the list alphabetically :D

mbelton-buildkite · 2023-10-04T01:53:57Z

pages/apis/rest_api/agents.md

@@ -15,7 +15,7 @@ curl "https://api.buildkite.com/v2/organizations/{org.slug}/agents"
    "id": "0b461f65-e7be-4c80-888a-ef11d81fd971",
    "graphql_id": "QWdlbnQtLS1mOTBhNzliNC01YjJlLTQzNzEtYjYxZS03OTA4ZDAyNmUyN2E=",
    "url": "https://api.buildkite.com/v2/organizations/my-great-org/agents/my-agent",
-    "web_url": "https://buildkite.com/organizations/buildkite/my-great-org/agents/0b461f65-e7be-4c80-888a-ef11d81fd971",
+    "web_url": "https://buildkite.com/organizations/my-great-org/agents/0b461f65-e7be-4c80-888a-ef11d81fd971",


pages/apis/graphql/cookbooks/pipeline_templates.md

pages/apis/rest_api/pipeline_templates.md

pages/apis/graphql/cookbooks/pipeline_templates.md

mbelton-buildkite · 2023-10-04T04:41:34Z

pages/apis/rest_api/pipeline_templates.md

+  </tr>
+  <tr>
+    <th><code>available</code></th>
+    <td>When set to <code>true</code>, non-admins can assign the pipeline template can assigned to pipelines.<br><em>Example:</em> <code>false</code></td>


Looks like this change didn't get applied quite right. Should be:

Suggested change

<td>When set to <code>true</code>, non-admins can assign the pipeline template can assigned to pipelines. Example: <code>false</code></td>

<td>When set to <code>true</code>, non-admins can assign the pipeline template to pipelines. Example: <code>false</code></td>

I think this mistake is made in a few places.

Hopefully that last commit I just pushed up covered the rest of it 🤞

mbelton-buildkite · 2023-10-04T04:49:05Z

pages/apis/rest_api/pipeline_templates.md

+  <tr><th><code>name</code></th><td>Name of the pipeline template</td></tr>
+  <tr><th><code>description</code></th><td>Description of the pipeline template</td></tr>
+  <tr><th><code>configuration</code></th><td>YAML step configuration for the pipeline template</td></tr>
+  <tr><th><code>available</code></th><td>When set to <code>true</code>, the pipeline template can assigned to pipelines by non-admins<br><em>Default:</em> <code>false</code></td></tr>


One last instance:

Suggested change

<tr><th><code>available</code></th><td>When set to <code>true</code>, the pipeline template can assigned to pipelines by non-admins Default: <code>false</code></td></tr>

<tr><th><code>available</code></th><td>When set to <code>true</code>, non-admins can assign the pipeline template to pipelines Default: <code>false</code></td></tr>

Did a full text search on the code just to be sure.. 😆
That ought to be it!

mbelton-buildkite

Looks good to me! Thanks for all your work on this! 😊

github-actions bot added api rest labels Sep 18, 2023

github-actions bot added the graphql label Sep 22, 2023

jonathanly changed the title ~~[EDGE-1520] Add pipeline templates rest api documentation~~ [EDGE-1520] Add pipeline templates rest & graphql api documentation Sep 22, 2023

mhaylock requested changes Sep 25, 2023

View reviewed changes

pages/apis/rest_api/pipeline_templates.md Show resolved Hide resolved

pages/apis/rest_api/pipeline_templates.md Outdated Show resolved Hide resolved

pages/apis/rest_api/pipeline_templates.md Outdated Show resolved Hide resolved

jonathanly mentioned this pull request Sep 29, 2023

Update generate graphql docs helper text #2505

Merged

jonathanly force-pushed the edge-1520-create-pipeline-template-rest-api-documentation branch from 8be7a5a to 4e73e17 Compare September 29, 2023 03:52

jonathanly marked this pull request as ready for review September 29, 2023 03:55

jonathanly requested review from mbelton-buildkite, MelissaKaulfuss and meiqimichelle as code owners September 29, 2023 03:55

dannymidnight mentioned this pull request Sep 29, 2023

Update README for generating GraphQL docs #2509

Merged

jonathanly force-pushed the edge-1520-create-pipeline-template-rest-api-documentation branch 2 times, most recently from e9552ea to f7526fd Compare September 29, 2023 06:29

jonathanly added 9 commits October 3, 2023 09:41

Fix indentation in code example

aeeacc0

Draft pipeline templates rest api documentation

d31f8fc

Add note re deleting a pipeline template when it is still assigned

afb1445

Generate pipeline template graphql documentation

c5c1818

Remove top level sidenav link and update url from local to prod urls

576be62

Link to pipeline templates page instead of pricing page

9070800

Add pipeline template graphql cookbook examples

861d405

Regenerate graphql docs

a028f8d

Add update cookbook index links with pipeline templates and sort list

7e0d3ed

jonathanly force-pushed the edge-1520-create-pipeline-template-rest-api-documentation branch from da7cd63 to 7e0d3ed Compare October 2, 2023 23:11

jonathanly requested a review from mhaylock October 2, 2023 23:12

Example formatting

f376798

jonathanly force-pushed the edge-1520-create-pipeline-template-rest-api-documentation branch from 06da97e to f376798 Compare October 2, 2023 23:16

jonathanly commented Oct 2, 2023

View reviewed changes

data/graphql/schema.graphql Outdated Show resolved Hide resolved

mhaylock requested changes Oct 3, 2023

View reviewed changes

jonathanly added 4 commits October 3, 2023 15:20

Refetch latest schema and regenerate graphql docs

846c62a

Use correct gql syntax

8f472e4

Fix 8 year old doc typo 😆

729d77f

Use acme-inc as org in example snippets

6e8fe10

jonathanly requested a review from mhaylock October 3, 2023 05:49

mhaylock approved these changes Oct 3, 2023

View reviewed changes

mbelton-buildkite reviewed Oct 4, 2023

View reviewed changes

jonathanly added 3 commits October 4, 2023 14:11

Link to enterprise pricing plan

f06384c

Sort cookbook index links in alphabetical order

9b5dc00

Formatting and grammar changes

9c7ce98

mbelton-buildkite reviewed Oct 4, 2023

View reviewed changes

pages/apis/graphql/cookbooks/pipeline_templates.md Outdated Show resolved Hide resolved

mbelton-buildkite reviewed Oct 4, 2023

View reviewed changes

More formatting and nav list ordering ✨

810210b

mbelton-buildkite reviewed Oct 4, 2023

View reviewed changes

More grammar alignment

45987ac

mbelton-buildkite approved these changes Oct 4, 2023

View reviewed changes

jonathanly merged commit 88b0309 into main Oct 4, 2023
1 check passed

jonathanly deleted the edge-1520-create-pipeline-template-rest-api-documentation branch October 4, 2023 05:06

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[EDGE-1520] Add pipeline templates rest & graphql api documentation #2479

[EDGE-1520] Add pipeline templates rest & graphql api documentation #2479

jonathanly commented Sep 18, 2023 •

edited

Loading

buildkite-docs-bot commented Sep 18, 2023

mhaylock left a comment

jonathanly Oct 2, 2023

mhaylock Oct 3, 2023

mhaylock left a comment

mhaylock Oct 3, 2023

mhaylock left a comment

mhaylock Oct 3, 2023

mbelton-buildkite Oct 4, 2023

mbelton-buildkite left a comment

mbelton-buildkite Oct 4, 2023

jonathanly Oct 4, 2023 •

edited

Loading

mbelton-buildkite Oct 4, 2023

jonathanly Oct 4, 2023

mbelton-buildkite Oct 4, 2023

mbelton-buildkite Oct 4, 2023

jonathanly Oct 4, 2023

mbelton-buildkite Oct 4, 2023

jonathanly Oct 4, 2023

mbelton-buildkite left a comment

	<td>When set to <code>true</code>, non-admins can assign the pipeline template can assigned to pipelines.<br><em>Example:</em> <code>false</code></td>
	<td>When set to <code>true</code>, non-admins can assign the pipeline template to pipelines.<br><em>Example:</em> <code>false</code></td>

	<tr><th><code>available</code></th><td>When set to <code>true</code>, the pipeline template can assigned to pipelines by non-admins<br><em>Default:</em> <code>false</code></td></tr>
	<tr><th><code>available</code></th><td>When set to <code>true</code>, non-admins can assign the pipeline template to pipelines<br><em>Default:</em> <code>false</code></td></tr>

[EDGE-1520] Add pipeline templates rest & graphql api documentation #2479

[EDGE-1520] Add pipeline templates rest & graphql api documentation #2479

Conversation

jonathanly commented Sep 18, 2023 • edited Loading

buildkite-docs-bot commented Sep 18, 2023

mhaylock left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mhaylock left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mhaylock left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mbelton-buildkite left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jonathanly Oct 4, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mbelton-buildkite left a comment

Choose a reason for hiding this comment

jonathanly commented Sep 18, 2023 •

edited

Loading

jonathanly Oct 4, 2023 •

edited

Loading