From 2268ddc7de0709cac5d657688732d215164128ee Mon Sep 17 00:00:00 2001 From: Evan Read Date: Thu, 1 Nov 2018 15:41:46 +1000 Subject: [PATCH] Implement some review comments Also: - Slight restructure. - Some Markdown improvements. --- doc/development/documentation/styleguide.md | 100 ++++++++++---------- 1 file changed, 50 insertions(+), 50 deletions(-) diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md index 07e247da5e6..e2c29ced517 100644 --- a/doc/development/documentation/styleguide.md +++ b/doc/development/documentation/styleguide.md @@ -62,7 +62,7 @@ with files organized in the [correct directory](index.md#documentation-directory link out to their external sites, documentation, and resources. - Do not duplicate information. - Structure content in alphabetical order in tables, lists, etc., unless there is -a logical reason not to (for example, when mirroring the UI or an ordered sequence). +a logical reason not to (for example, when mirroring the UI or an ordered sequence). ## Language @@ -398,20 +398,20 @@ The following are styles to follow when describing UI elements on a screen: ### Verbs for UI elements -The following are verbs that should be used in preference to alternatives. +The following are recommended verbs for specific uses. -| Use | Used for | Do not use | -|:---------|:--------------------------------|:---------------------------| -| "click" | buttons, links, menu items | "hit", "press", "select" | -| "check" | checkboxes | "enable", "click", "press" | -| "select" | dropdowns | "pick" | -| "expand" | expandable sections | "open" | +| Recommended | Used for | Alternatives | +|:------------|:---------------------------|:---------------------------| +| "click" | buttons, links, menu items | "hit", "press", "select" | +| "check" | checkboxes | "enable", "click", "press" | +| "select" | dropdowns | "pick" | +| "expand" | expandable sections | "open" | ### Other Verbs -| Use | Used for | Do not use | -|:---------|:--------------------------------|:---------------------------| -| "go" | making a browser go to location | "navigate", "open" | +| Recommended | Used for | Alternatives | +|:------------|:--------------------------------|:-------------------| +| "go" | making a browser go to location | "navigate", "open" | ### GitLab versions and tiers @@ -564,38 +564,15 @@ the style below as a guide: In this case: -- Before each step list the installation method is declared in bold +- Before each step list the installation method is declared in bold. - Three dashes (`---`) are used to create a horizontal line and separate the - two methods + two methods. - The code blocks are indented one or more spaces under the list item to render - correctly -- Different highlighting languages are used for each config in the code block -- The [references](#references) guide is used for reconfigure/restart + correctly. +- Different highlighting languages are used for each config in the code block. +- The [references](#references) guide is used for reconfigure/restart. -### Fake tokens - -There may be times where a token is needed to demonstrate an API call using -cURL or a variable used in CI. It is strongly advised not to use real -tokens in documentation even if the probability of a token being exploited is -low. - -You can use the following fake tokens as examples. - -| **Token type** | **Token value** | -|:----------------------|:-------------------------------------------------------------------| -| Private user token | `` | -| Personal access token | `n671WNGecHugsdEDPsyo` | -| Application ID | `2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6` | -| Application secret | `04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df` | -| CI/CD variable | `Li8j-mLUVA3eZYjPfd_H` | -| Specific Runner token | `yrnZW46BrtBFqM7xDzE7dddd` | -| Shared Runner token | `6Vk7ZsosqQyfreAxXTZr` | -| Trigger token | `be20d8dcc028677c931e04f3871a9b` | -| Webhook secret token | `6XhDroRcYPM5by_h-HLY` | -| Health check token | `Tu7BgjR9qeZTEyRzGG2P` | -| Request profile token | `7VgpS4Ax5utVD2esNstz` | - -### API +## API Here is a list of must-have items. Use them in the exact order that appears on this document. Further explanation is given below. @@ -611,7 +588,30 @@ on this document. Further explanation is given below. - Every method must have a cURL example. - Every method must have a response body (in JSON format). -#### Method description +### Fake tokens + +There may be times where a token is needed to demonstrate an API call using +cURL or a variable used in CI. It is strongly advised not to use real +tokens in documentation even if the probability of a token being exploited is +low. + +You can use the following fake tokens as examples. + +| Token type | Token value | +|:----------------------|:-------------------------------------------------------------------| +| Private user token | `` | +| Personal access token | `n671WNGecHugsdEDPsyo` | +| Application ID | `2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6` | +| Application secret | `04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df` | +| CI/CD variable | `Li8j-mLUVA3eZYjPfd_H` | +| Specific Runner token | `yrnZW46BrtBFqM7xDzE7dddd` | +| Shared Runner token | `6Vk7ZsosqQyfreAxXTZr` | +| Trigger token | `be20d8dcc028677c931e04f3871a9b` | +| Webhook secret token | `6XhDroRcYPM5by_h-HLY` | +| Health check token | `Tu7BgjR9qeZTEyRzGG2P` | +| Request profile token | `7VgpS4Ax5utVD2esNstz` | + +### Method description Use the following table headers to describe the methods. Attributes should always be in code blocks using backticks (``` ` ```). @@ -627,7 +627,7 @@ Rendered example: |:----------|:-------|:---------|:--------------------| | `user` | string | yes | The GitLab username | -#### cURL commands +### cURL commands - Use `https://gitlab.example.com/api/v4/` as an endpoint. - Wherever needed use this personal access token: ``. @@ -644,11 +644,11 @@ Rendered example: | `-X PUT` | Use this method when updating existing objects | | `-X DELETE` | Use this method when removing existing objects | -#### cURL Examples +### cURL Examples Below is a set of [cURL][] examples that you can use in the API documentation. -##### Simple cURL command +#### Simple cURL command Get the details of a group: @@ -656,7 +656,7 @@ Get the details of a group: curl --header "PRIVATE-TOKEN: " https://gitlab.example.com/api/v4/groups/gitlab-org ``` -##### cURL example with parameters passed in the URL +#### cURL example with parameters passed in the URL Create a new project under the authenticated user's namespace: @@ -664,7 +664,7 @@ Create a new project under the authenticated user's namespace: curl --request POST --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects?name=foo" ``` -##### Post data using cURL's --data +#### Post data using cURL's --data Instead of using `-X POST` and appending the parameters to the URI, you can use cURL's `--data` option. The example below will create a new project `foo` under @@ -674,7 +674,7 @@ the authenticated user's namespace. curl --data "name=foo" --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects" ``` -##### Post data using JSON content +#### Post data using JSON content > **Note:** In this example we create a new group. Watch carefully the single and double quotes. @@ -683,7 +683,7 @@ and double quotes. curl --request POST --header "PRIVATE-TOKEN: " --header "Content-Type: application/json" --data '{"path": "my-group", "name": "My group"}' https://gitlab.example.com/api/v4/groups ``` -##### Post data using form-data +#### Post data using form-data Instead of using JSON or urlencode you can use multipart/form-data which properly handles data encoding: @@ -695,7 +695,7 @@ curl --request POST --header "PRIVATE-TOKEN: " --form "title= The above example is run by and administrator and will add an SSH public key titled ssh-key to user's account which has an id of 25. -##### Escape special characters +#### Escape special characters Spaces or slashes (`/`) may sometimes result to errors, thus it is recommended to escape them when possible. In the example below we create a new issue which @@ -708,7 +708,7 @@ curl --request POST --header "PRIVATE-TOKEN: " "https://gitla Use `%2F` for slashes (`/`). -##### Pass arrays to API calls +#### Pass arrays to API calls The GitLab API sometimes accepts arrays of strings or integers. For example, to restrict the sign-up e-mail domains of a GitLab instance to `*.example.com` and