kotovalexarian-likes-gitlab/gitlab-org--gitlab-foss
1
0
Fork 0
Code Releases Activity

Implement some review comments

Browse source 
Also:

- Slight restructure.
- Some Markdown improvements.
This commit is contained in:
Evan Read 2018-11-01 15:41:46 +10:00
parent 40aba81218
commit 2268ddc7de
1 changed files with 50 additions and 50 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

100
doc/development/documentation/styleguide.md
View file

@ -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 | `<your_access_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 | `<your_access_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: `<your_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: <your_access_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: <your_access_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: <your_access_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: <your_access_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: <your_access_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: <your_access_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