Refactor documentation API

This is a meta issue to track the status of API documentation refactoring. Taken from https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/681.

---

All docs should follow the documentation styleguide:

• Use tables for attributes
• Use one curl example with each method call
• Make sure every method call has a response body (in json format)

GitLab

• README.md - https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2476
• branches.md - https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2464
• builds.md https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2207
• build_triggers.md - https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2286
• build_variables.md https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2264
• commits.md - https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2465
• deploy_key_multiple_projects.md - https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2468
• deploy_keys.md - https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2467
• files.md - non-existent
• groups.md - https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2469
• issues.md - https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2466
• keys.md - https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2470
• labels.md - https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2471
• merge_requests.md
• milestones.md
• namespaces.md - https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2472
• notes.md
• oauth2.md
• project_snippets.md
• projects.md
• repositories.md
• repository_files.md
• services.md
• session.md - https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2473
• settings.md - https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2474
• system_hooks.md - https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2475
• tags.md
• users.md

GitLab CI

• README.md
• builds.md https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2207
• commits.md https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2465
• projects.md
• runners.md

Notes

• Document that groups can only created by users which are allowed to create groups, see https://gitlab.com/gitlab-org/gitlab-ce/issues/4259#note_3031554
• Inconsistency between doc and API for user update https://gitlab.com/gitlab-org/gitlab-ce/issues/1042
• users.md (!2089 (merged) and https://dev.gitlab.org/gitlab/gitlabhq/issues/1244#note_64122)
• Confusion between id and iid - https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4030

---

Sorted by word count

89 milestones.md
102 oauth2.md
110 repository_files.md
118 project_snippets.md
150 tags.md
178 repositories.md
249 README.md
261 notes.md
474 merge_requests.md
575 users.md
696 services.md
818 projects.md