Merge pull request #13 from go-vela/jan13

docs: moved it all over

docs/reference/_index.md

@@ -0,0 +1,10 @@
+---
+title: "Reference"
+linkTitle: "Reference"
+layout: reference
+description: >
+  Reference information for creating pipelines and using the CLI, API, or SDKs.
+menu:
+  main:
+    weight: 605
+---

docs/reference/api/_category_.json

@@ -1,5 +1,7 @@
 {
   "label": "API",
   "position": 1,
-  "link": {"type": "generated-index"},
+  "link": {
+    "type": "generated-index"
+  }
 }

docs/reference/api/admin/admin.md

@@ -0,0 +1,14 @@
+---
+title: "Admin"
+linkTitle: "Admin"
+description: >
+  Learn how to use API endpoints as an admin of the platform.
+---
+
+The below endpoints are available to operate on as an admin of the platform.
+
+:::warning
+This section assumes you already know how to authenticate to the API.
+
+To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication/).
+:::

docs/reference/api/admin/build.md

@@ -11,6 +11,10 @@ description: >
 PUT  /api/v1/admin/build
 ```
 
+## Permissions
+
+COMING SOON!
+
 ## Responses
 
 | Status Code | Description                                         |

docs/reference/api/admin/build-queue.md → docs/reference/api/admin/build_queue.md

@@ -11,6 +11,10 @@ description: >
 GET  /api/v1/admin/builds/queue
 ```
 
+## Permissions
+
+COMING SOON!
+
 ## Responses
 
 | Status Code | Description                                         |

docs/reference/api/admin/clean.md

@@ -0,0 +1,68 @@
+---
+title: "Clean"
+linkTitle: "Clean"
+description: >
+  Learn how to clean dangling resources as an admin in the system.
+---
+
+## Endpoint
+
+```
+PUT  /api/v1/admin/clean
+```
+
+## Filters
+
+The following optional filters are available:
+
+| Name       | Description                                                                                                | 
+| --------   | ---------------------------------------------------------------------------------------------------------- |
+| `before`   | clean resources created before a certain time (UNIX Epoch, default = "now" minus repo timeout + 5 minutes) |
+
+## Permissions
+
+COMING SOON!
+
+## Responses
+
+| Status Code | Description                                         |
+| ----------- | --------------------------------------------------- |
+| `200`       | indicates the request has succeeded                 |
+| `400`       | indicates bad request                               |
+| `401`       | indicates user does not have proper permissions     |
+| `500`       | indicates internal server issue while cleaning      |
+
+## Sample
+
+:::warning
+This section assumes you already know how to authenticate to the API.
+
+To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication/).
+:::
+
+#### File
+
+```json
+{
+  "message": "this resource has been set to error by platform admins during maintenance"
+}
+```
+
+Note: the default value for `message` is "build cleaned by platform admin"
+
+#### Request
+
+```sh
+curl \
+  -X PUT \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -d "@data.json" \
+  "http://127.0.0.1:8080/api/v1/admin/clean"
+```
+
+#### Response
+
+```json
+  "42 builds cleaned. 42 services cleaned. 42 steps cleaned."
+```

docs/reference/api/admin/hook.md

@@ -0,0 +1,83 @@
+---
+title: "Hook"
+linkTitle: "Hook"
+description: >
+  Learn how to update a hook as an admin in the system.
+---
+
+## Endpoint
+
+```
+PUT  /api/v1/admin/hook
+```
+
+## Permissions
+
+COMING SOON!
+
+## Responses
+
+| Status Code | Description                                         |
+| ----------- | --------------------------------------------------- |
+| `200`       | indicates the request has succeeded                 |
+| `401`       | indicates the user does not have proper permissions |
+
+## Sample
+
+:::warning
+This section assumes you already know how to authenticate to the API.
+
+To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication/).
+:::
+
+Note: You must provide the entire hook object, as this endpoint overwrites the
+existing entry for the hook.
+
+#### File
+
+```json
+{
+  "id": 1,
+  "repo_id": 1,
+  "build_id": 1,
+  "number": 1,
+  "source_id": "c8da1302-07d6-11ea-882f-4893bca275b8",
+  "created": "1563474076",
+  "host": "github.com",
+  "event": "push",
+  "branch": "main",
+  "error": "",
+  "status": "failure",
+  "link": ""
+}
+```
+
+#### Request
+
+```sh
+curl \
+  -X PUT \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -d "@data.json" \
+  "http://127.0.0.1:8080/api/admin/hook"
+```
+
+#### Response
+
+```json
+{
+  "id": 1,
+  "repo_id": 1,
+  "build_id": 1,
+  "number": 1,
+  "source_id": "c8da1302-07d6-11ea-882f-4893bca275b8",
+  "created": "1563474076",
+  "host": "github.com",
+  "event": "push",
+  "branch": "main",
+  "error": "",
+  "status": "failure",
+  "link": ""
+}
+```

docs/reference/api/admin/repo.md

@@ -0,0 +1,101 @@
+---
+title: "Repo"
+linkTitle: "Repo"
+description: >
+  Learn how to update a repo as an admin in the system.
+---
+
+## Endpoint
+
+```
+PUT  /api/v1/admin/repo
+```
+
+## Permissions
+
+COMING SOON!
+
+## Responses
+
+| Status Code | Description                                         |
+| ----------- | --------------------------------------------------- |
+| `200`       | indicates the request has succeeded                 |
+| `401`       | indicates the user does not have proper permissions |
+
+## Sample
+
+:::warning
+This section assumes you already know how to authenticate to the API.
+
+To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication/).
+:::
+
+Note: You must provide the entire repo object, as this endpoint overwrites the
+existing entry for the repo.
+
+#### File
+
+```json
+{
+  "id": 1,
+  "user_id": 1,
+  "org": "github",
+  "name": "octocat",
+  "full_name": "github/octocat",
+  "link": "https://github.com/github/octocat",
+  "clone": "https://github.com/github/octocat.git",
+  "branch": "main",
+  "build_limit": 10,
+  "timeout": 60,
+  "counter": 0,
+  "visibility": "public",
+  "private": false,
+  "trusted": true,
+  "active": true,
+  "allow_pull": true,
+  "allow_push": true,
+  "allow_deploy": false,
+  "allow_tag": true,
+  "allow_comment": false,
+  "pipeline_type": "yaml"
+}
+```
+
+#### Request
+
+```sh
+curl \
+  -X PUT \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -d "@data.json" \
+  "http://127.0.0.1:8080/api/v1/admin/repo"
+```
+
+#### Response
+
+```json
+{
+  "id": 1,
+  "user_id": 1,
+  "org": "github",
+  "name": "octocat",
+  "full_name": "github/octocat",
+  "link": "https://github.com/github/octocat",
+  "clone": "https://github.com/github/octocat.git",
+  "branch": "main",
+  "build_limit": 10,
+  "timeout": 60,
+  "counter": 0,
+  "visibility": "public",
+  "private": false,
+  "trusted": true,
+  "active": true,
+  "allow_pull": true,
+  "allow_push": true,
+  "allow_deploy": false,
+  "allow_tag": true,
+  "allow_comment": false,
+  "pipeline_type": "yaml"
+}
+```