Merge branch 'doc_refactor_commits_api' into 'master'

Refactor commits API documentation

Blocked by https://gitlab.com/gitlab-org/gitlab-ce/issues/10960 which needs to be fixed or documented.

Closes #4217 

See merge request !2465

doc/ci/api/commits.md

 # Commits API
 
+**DEPRECATED**
+
+Since GitLab 8.1, there is a new commit status API. Please see the [revised
+documentation](../../api/commits.md#commit-status).
+
+---
+
 __Authentication is done by GitLab CI project token__
 
 ## Commits