1
0
mirror of synced 2025-12-21 10:57:10 -05:00

Update copy syntax to CommonMark compliant

This commit is contained in:
Kevin Heis
2023-06-12 08:11:20 -07:00
parent a7a368871e
commit 5f0ca62ed3
239 changed files with 736 additions and 736 deletions

View File

@@ -43,7 +43,7 @@ If you want to use the {% data variables.product.company_short %} REST API for p
First, import `Octokit` from `octokit`. Then, pass your {% data variables.product.pat_generic %} when you create an instance of `Octokit`. In the following example, replace `YOUR-TOKEN` with a reference to your {% data variables.product.pat_generic %}.{% ifversion ghes or ghae %} Replace `HOSTNAME` with the name of {% data variables.location.product_location %}.{% endif %}
```javascript{:copy}
```javascript copy
import { Octokit } from "octokit";
const octokit = new Octokit({ {% ifversion ghes or ghae %}
@@ -58,7 +58,7 @@ If you want to use the API on behalf of an organization or another user, {% data
Instead of importing `Octokit` from `octokit`, import `App`. In the following example, replace `APP_ID` with a reference to your app's ID. Replace `PRIVATE_KEY` with a reference to your app's private key. Replace `INSTALLATION_ID` with the ID of the installation of your app that you want to authenticate on behalf of. You can find your app's ID and generate a private key on the settings page for your app. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps)." You can get an installation ID with the `GET /users/{username}/installation`, `GET /repos/{owner}/{repo}/installation`, or `GET /orgs/{org}/installation` endpoints. For more information, see "[AUTOTITLE](/rest/apps/apps)" in the REST reference documentation.{% ifversion ghes or ghae %} Replace `HOSTNAME` with the name of {% data variables.location.product_location %}.{% endif %}
```javascript{:copy}
```javascript copy
import { App } from "octokit";
const app = new App({
@@ -92,7 +92,7 @@ For example, this workflow step stores `GITHUB_TOKEN` in an environment variable
The script that the workflow runs uses `process.env.TOKEN` to authenticate:
```javascript{:copy}
```javascript copy
import { Octokit } from "octokit";
const octokit = new Octokit({ {% ifversion ghes or ghae %}
@@ -105,7 +105,7 @@ const octokit = new Octokit({ {% ifversion ghes or ghae %}
You can use the REST API without authentication, although you will have a lower rate limit and will not be able to use some endpoints. To create an instance of `Octokit` without authenticating, do not pass the `auth` argument.{% ifversion ghes or ghae %} Set the base URL to `{% data variables.product.api_url_code %}`. Replace `[hostname]` with the name of {% data variables.location.product_location %}.{% endif %}
```javascript{:copy}
```javascript copy
import { Octokit } from "octokit";
const octokit = new Octokit({ {% ifversion ghes or ghae %}
@@ -121,7 +121,7 @@ Octokit supports multiple ways of making requests. You can use the `request` met
To use the `request` method to make requests, pass the HTTP method and path as the first argument. Pass any body, query, or path parameters in an object as the second argument. For example, to make a `GET` request to `/repos/{owner}/{repo}/issues` and pass the `owner`, `repo`, and `per_page` parameters:
```javascript{:copy}
```javascript copy
await octokit.request("GET /repos/{owner}/{repo}/issues", {
owner: "github",
repo: "docs",
@@ -131,7 +131,7 @@ await octokit.request("GET /repos/{owner}/{repo}/issues", {
The `request` method automatically passes the `Accept: application/vnd.github+json` header. To pass additional headers or a different `Accept` header, add a `headers` property to the object that is passed as a second argument. The value of the `headers` property is an object with the header names as keys and header values as values. For example, to send a `content-type` header with a value of `text/plain`{% ifversion api-date-versioning %} and a `x-github-api-version` header with a value of `{{ allVersions[currentVersion].latestApiVersion }}`{% endif %}:
```javascript{:copy}
```javascript copy
await octokit.request("POST /markdown/raw", {
text: "Hello **world**",
headers: {
@@ -145,7 +145,7 @@ await octokit.request("POST /markdown/raw", {
Every REST API endpoint has an associated `rest` endpoint method in Octokit. These methods generally autocomplete in your IDE for convenience. You can pass any parameters as an object to the method.
```javascript{:copy}
```javascript copy
await octokit.rest.issues.listForRepo({
owner: "github",
repo: "docs",
@@ -161,7 +161,7 @@ If the endpoint is paginated and you want to fetch more than one page of results
For example, the following example gets all of the issues from the `github/docs` repository. Although it requests 100 issues at a time, the function won't return until the last page of data is reached.
```javascript{:copy}
```javascript copy
const issueData = await octokit.paginate("GET /repos/{owner}/{repo}/issues", {
owner: "github",
repo: "docs",
@@ -174,7 +174,7 @@ const issueData = await octokit.paginate("GET /repos/{owner}/{repo}/issues", {
The `paginate` method accepts an optional map function, which you can use to collect only the data that you want from the response. This reduces memory usage by your script. The map function can take a second argument, `done`, which you can call to end the pagination before the last page is reached. This lets you fetch a subset of pages. For example, the following example continues to fetch results until an issue that includes "test" in the title is returned. For the pages of data that were returned, only the issue title and author are stored.
```javascript{:copy}
```javascript copy
const issueData = await octokit.paginate("GET /repos/{owner}/{repo}/issues", {
owner: "github",
repo: "docs",
@@ -194,7 +194,7 @@ const issueData = await octokit.paginate("GET /repos/{owner}/{repo}/issues", {
Instead of fetching all of the results at once, you can use `octokit.paginate.iterator()` to iterate through a single page at a time. For example, the following example fetches one page of results at a time and processes each object from the page before fetching the next page. Once an issue that includes "test" in the title is reached, the script stops the iteration and returns the issue title and issue author of each object that was processed. The iterator is the most memory efficient method for fetching paginated data.
```javascript{:copy}
```javascript copy
const iterator = octokit.paginate.iterator("GET /repos/{owner}/{repo}/issues", {
owner: "github",
repo: "docs",
@@ -221,7 +221,7 @@ for await (const {data} of iterator) {
You can use the `paginate` method with the `rest` endpoint methods as well. Pass the `rest` endpoint method as the first argument. Pass any parameters as the second argument.
```javascript{:copy}
```javascript copy
const iterator = octokit.paginate.iterator(octokit.rest.issues.listForRepo, {
owner: "github",
repo: "docs",
@@ -240,7 +240,7 @@ For more information about pagination, see "[AUTOTITLE](/rest/guides/using-pagin
Sometimes, the {% data variables.product.company_short %} REST API will return an error. For example, you will get an error if your access token is expired or if you omitted a required parameter. Octokit.js automatically retries the request when it gets an error other than `400 Bad Request`, `401 Unauthorized`, `403 Forbidden`, `404 Not Found`, and `422 Unprocessable Entity`. If an API error occurs even after retries, Octokit.js throws an error that includes the HTTP status code of the response (`response.status`) and the response headers (`response.headers`). You should handle these errors in your code. For example, you can use a try/catch block to catch errors:
```javascript{:copy}
```javascript copy
let filesChanged = []
try {
@@ -269,7 +269,7 @@ try {
Sometimes, {% data variables.product.company_short %} uses a 4xx status code to indicate a non-error response. If the endpoint you are using does this, you can add additional handling for specific errors. For example, the `GET /user/starred/{owner}/{repo}` endpoint will return a `404` if the repository is not starred. The following example uses the `404` response to indicate that the repository was not starred; all other errors codes are treated as errors.
```javascript{:copy}
```javascript copy
try {
await octokit.request("GET /user/starred/{owner}/{repo}", {
owner: "github",
@@ -294,7 +294,7 @@ try {
If you receive a rate limit error, you may want to retry your request after waiting. When you are rate limited, {% data variables.product.company_short %} responds with a `403 Forbidden` error and the `x-ratelimit-remaining` response header value will be `"0"`. The response headers will include a `x-ratelimit-reset` header, which tells you the time at which the current rate limit window resets, in UTC epoch seconds. You can retry your request after the time specified by `x-ratelimit-reset`.
```javascript{:copy}
```javascript copy
async function requestRetry(route, parameters) {
try {
const response = await octokit.request(route, parameters);
@@ -323,7 +323,7 @@ const response = await requestRetry("GET /repos/{owner}/{repo}/issues", {
The `request` method returns a promise that resolves to an object if the request was successful. The object properties are `data` (the response body returned by the endpoint), `status` (the HTTP response code), `url` (the URL of the request), and `headers` (an object containing the response headers). Unless otherwise specified, the response body is in JSON format. Some endpoints do not return a response body; in those cases, the `data` property is omitted.
```javascript{:copy}
```javascript copy
const response = await octokit.request("GET /repos/{owner}/{repo}/issues/{issue_number}", {
owner: "github",
repo: "docs",
@@ -341,7 +341,7 @@ console.log(`The issue title is: ${response.data.title}`)
Similarly, the `paginate` method returns a promise. If the request was successful, the promise resolves to an array of data returned by the endpoint. Unlike the `request` method, the `paginate` method does not return the status code, URL, or headers.
```javascript{:copy}
```javascript copy
const data = await octokit.paginate("GET /repos/{owner}/{repo}/issues", {
owner: "github",
repo: "docs",
@@ -361,7 +361,7 @@ Here is a full example script that uses Octokit.js. The script imports `Octokit`
The `getChangedFiles` function gets all of the files changed for a pull request. The `commentIfDataFilesChanged` function calls the `getChangedFiles` function. If any of the files that the pull request changed include `/data/` in the file path, then the function will comment on the pull request.
```javascript{:copy}
```javascript copy
import { Octokit } from "octokit";
const octokit = new Octokit({ {% ifversion ghes or ghae %}