Commit 2268ddc7 authored by Evan Read's avatar Evan Read

Implement some review comments

Also:

- Slight restructure.
- Some Markdown improvements.
parent 40aba812
......@@ -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,13 +564,29 @@ 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.
## 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.
- Every method must have the REST API request. For example:
```
GET /projects/:id/repository/branches
```
- Every method must have a detailed
[description of the parameters](#method-description).
- Every method must have a cURL example.
- Every method must have a response body (in JSON format).
### Fake tokens
......@@ -581,7 +597,7 @@ low.
You can use the following fake tokens as examples.
| **Token type** | **Token value** |
| Token type | Token value |
|:----------------------|:-------------------------------------------------------------------|
| Private user token | `<your_access_token>` |
| Personal access token | `n671WNGecHugsdEDPsyo` |
......@@ -595,23 +611,7 @@ You can use the following fake tokens as examples.
| Health check token | `Tu7BgjR9qeZTEyRzGG2P` |
| Request profile token | `7VgpS4Ax5utVD2esNstz` |
### 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.
- Every method must have the REST API request. For example:
```
GET /projects/:id/repository/branches
```
- Every method must have a detailed
[description of the parameters](#method-description).
- Every method must have a cURL example.
- Every method must have a response body (in JSON format).
#### Method description
### 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
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment