From 9637fa7259fa13701d035763b820900048c92f08 Mon Sep 17 00:00:00 2001 From: Ian Eaves Date: Thu, 2 Nov 2023 16:16:08 -0500 Subject: [PATCH] big docs updates --- docs/pages/_meta.json | 5 +- docs/pages/api-docs.mdx | 8 + docs/pages/api/index.mdx | 4 - docs/pages/api/openapi.yaml | 1272 ----------------- docs/pages/api/server.mdx | 8 - docs/pages/community.mdx | 25 + docs/pages/community/_meta.json | 7 - docs/pages/community/slack.mdx | 9 - docs/pages/concepts.mdx | 16 + ...ibutor-guidelines.mdx => contributing.mdx} | 0 docs/pages/contributing/_meta.json | 1 + .../clone-the-repo.mdx | 0 .../deployment.mdx | 4 +- .../new-integrations.mdx | 2 +- docs/pages/deployment.mdx | 33 + docs/pages/deployment/kubernetes.mdx | 10 + docs/pages/examples.mdx | 9 + docs/pages/integrations.mdx | 22 + docs/pages/server.mdx | 45 + docs/pages/server/_meta.json | 8 +- docs/pages/server/graphql-api.mdx | 10 +- docs/pages/server/index.mdx | 21 - docs/pages/server/rest-api.mdx | 50 + docs/pages/tooling.mdx | 10 + docs/pages/web-app.mdx | 16 + docs/pages/web-app/_meta.json | 3 - docs/pages/web-app/index.mdx | 9 - 27 files changed, 263 insertions(+), 1344 deletions(-) create mode 100644 docs/pages/api-docs.mdx delete mode 100644 docs/pages/api/index.mdx delete mode 100644 docs/pages/api/openapi.yaml delete mode 100644 docs/pages/api/server.mdx create mode 100644 docs/pages/community.mdx delete mode 100644 docs/pages/community/_meta.json delete mode 100644 docs/pages/community/slack.mdx create mode 100644 docs/pages/concepts.mdx rename docs/pages/{community/contributor-guidelines.mdx => contributing.mdx} (100%) create mode 100644 docs/pages/contributing/_meta.json rename docs/pages/{community => contributing}/clone-the-repo.mdx (100%) rename docs/pages/{community => contributing}/deployment.mdx (97%) rename docs/pages/{community => contributing}/new-integrations.mdx (99%) create mode 100644 docs/pages/deployment.mdx create mode 100644 docs/pages/deployment/kubernetes.mdx create mode 100644 docs/pages/examples.mdx create mode 100644 docs/pages/integrations.mdx create mode 100644 docs/pages/server.mdx delete mode 100644 docs/pages/server/index.mdx create mode 100644 docs/pages/server/rest-api.mdx create mode 100644 docs/pages/tooling.mdx create mode 100644 docs/pages/web-app.mdx delete mode 100644 docs/pages/web-app/index.mdx diff --git a/docs/pages/_meta.json b/docs/pages/_meta.json index c048c4c1e..0cd03e7f5 100644 --- a/docs/pages/_meta.json +++ b/docs/pages/_meta.json @@ -2,13 +2,14 @@ "index": "Home", "introduction": "What is Grai?", "quick-start": "Quick Start", - "community": "Community", "concepts": "Key Concepts", + "examples": "Examples", "tooling": "Tooling", "integrations": "Integrations", "server": "Server", "web-app": "Web App", "deployment": "Deployment", - "examples": "Examples", + "community": "Community", + "contributing": "Contributing", "api-docs": "API" } diff --git a/docs/pages/api-docs.mdx b/docs/pages/api-docs.mdx new file mode 100644 index 000000000..051474f7a --- /dev/null +++ b/docs/pages/api-docs.mdx @@ -0,0 +1,8 @@ +--- +title: API Reference Documentation +description: You can find reference documentation for each Grai library component here +--- + +# API Reference Documentation + +This directory contains reference documentation for each Grai library component. diff --git a/docs/pages/api/index.mdx b/docs/pages/api/index.mdx deleted file mode 100644 index 729ff63cc..000000000 --- a/docs/pages/api/index.mdx +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: "API" -description: API Documenation for Grai ---- diff --git a/docs/pages/api/openapi.yaml b/docs/pages/api/openapi.yaml deleted file mode 100644 index 21bafcc82..000000000 --- a/docs/pages/api/openapi.yaml +++ /dev/null @@ -1,1272 +0,0 @@ -openapi: 3.0.3 -info: - title: "" - version: 0.0.0 -paths: - /api/v1/auth/api-token/: - post: - operationId: auth_api_token_create - tags: - - auth - requestBody: - content: - application/x-www-form-urlencoded: - schema: - $ref: "#/components/schemas/AuthToken" - multipart/form-data: - schema: - $ref: "#/components/schemas/AuthToken" - application/json: - schema: - $ref: "#/components/schemas/AuthToken" - required: true - security: - - jwtAuth: [] - - cookieAuth: [] - - tokenAuth: [] - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/AuthToken" - description: "" - /api/v1/auth/is-authenticated/: - get: - operationId: auth_is_authenticated_retrieve - tags: - - auth - security: - - cookieAuth: [] - - tokenAuth: [] - - basicAuth: [] - - jwtAuth: [] - responses: - "200": - description: No response body - /api/v1/auth/jwttoken/: - post: - operationId: auth_jwttoken_create - description: |- - Takes a set of user credentials and returns an access and refresh JSON web - token pair to prove the authentication of those credentials. - tags: - - auth - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/TokenObtainPair" - application/x-www-form-urlencoded: - schema: - $ref: "#/components/schemas/TokenObtainPair" - multipart/form-data: - schema: - $ref: "#/components/schemas/TokenObtainPair" - required: true - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/TokenObtainPair" - description: "" - /api/v1/auth/jwttoken/refresh/: - post: - operationId: auth_jwttoken_refresh_create - description: |- - Takes a refresh type JSON web token and returns an access type JSON web - token if the refresh token is valid. - tags: - - auth - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/TokenRefresh" - application/x-www-form-urlencoded: - schema: - $ref: "#/components/schemas/TokenRefresh" - multipart/form-data: - schema: - $ref: "#/components/schemas/TokenRefresh" - required: true - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/TokenRefresh" - description: "" - /api/v1/auth/token/verify/: - post: - operationId: auth_token_verify_create - description: |- - Takes a token and indicates if it is valid. This view provides no - information about a token's fitness for a particular use. - tags: - - auth - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/TokenVerify" - application/x-www-form-urlencoded: - schema: - $ref: "#/components/schemas/TokenVerify" - multipart/form-data: - schema: - $ref: "#/components/schemas/TokenVerify" - required: true - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/TokenVerify" - description: "" - /api/v1/connections/: - get: - operationId: connections_list - tags: - - connections - security: - - cookieAuth: [] - - tokenAuth: [] - - basicAuth: [] - - jwtAuth: [] - responses: - "200": - content: - application/json: - schema: - type: array - items: - $ref: "#/components/schemas/Connection" - description: "" - post: - operationId: connections_create - tags: - - connections - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/Connection" - application/x-www-form-urlencoded: - schema: - $ref: "#/components/schemas/Connection" - multipart/form-data: - schema: - $ref: "#/components/schemas/Connection" - required: true - security: - - cookieAuth: [] - - tokenAuth: [] - - basicAuth: [] - - jwtAuth: [] - responses: - "201": - content: - application/json: - schema: - $ref: "#/components/schemas/Connection" - description: "" - /api/v1/connections/{id}/: - get: - operationId: connections_retrieve - parameters: - - in: path - name: id - schema: - type: string - format: uuid - description: A UUID string identifying this connection. - required: true - tags: - - connections - security: - - cookieAuth: [] - - tokenAuth: [] - - basicAuth: [] - - jwtAuth: [] - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/Connection" - description: "" - put: - operationId: connections_update - parameters: - - in: path - name: id - schema: - type: string - format: uuid - description: A UUID string identifying this connection. - required: true - tags: - - connections - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/Connection" - application/x-www-form-urlencoded: - schema: - $ref: "#/components/schemas/Connection" - multipart/form-data: - schema: - $ref: "#/components/schemas/Connection" - required: true - security: - - cookieAuth: [] - - tokenAuth: [] - - basicAuth: [] - - jwtAuth: [] - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/Connection" - description: "" - patch: - operationId: connections_partial_update - parameters: - - in: path - name: id - schema: - type: string - format: uuid - description: A UUID string identifying this connection. - required: true - tags: - - connections - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/PatchedConnection" - application/x-www-form-urlencoded: - schema: - $ref: "#/components/schemas/PatchedConnection" - multipart/form-data: - schema: - $ref: "#/components/schemas/PatchedConnection" - security: - - cookieAuth: [] - - tokenAuth: [] - - basicAuth: [] - - jwtAuth: [] - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/Connection" - description: "" - delete: - operationId: connections_destroy - parameters: - - in: path - name: id - schema: - type: string - format: uuid - description: A UUID string identifying this connection. - required: true - tags: - - connections - security: - - cookieAuth: [] - - tokenAuth: [] - - basicAuth: [] - - jwtAuth: [] - responses: - "204": - description: No response body - /api/v1/connectors/: - get: - operationId: connectors_list - tags: - - connectors - security: - - cookieAuth: [] - - tokenAuth: [] - - basicAuth: [] - - jwtAuth: [] - responses: - "200": - content: - application/json: - schema: - type: array - items: - $ref: "#/components/schemas/Connector" - description: "" - /api/v1/connectors/{id}/: - get: - operationId: connectors_retrieve - parameters: - - in: path - name: id - schema: - type: string - format: uuid - description: A UUID string identifying this connector. - required: true - tags: - - connectors - security: - - cookieAuth: [] - - tokenAuth: [] - - basicAuth: [] - - jwtAuth: [] - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/Connector" - description: "" - /api/v1/external-runs/: - post: - operationId: external_runs_create - tags: - - external-runs - security: - - jwtAuth: [] - - cookieAuth: [] - - tokenAuth: [] - responses: - "200": - description: No response body - /api/v1/lineage/edges/: - get: - operationId: lineage_edges_list - tags: - - lineage - security: - - cookieAuth: [] - - tokenAuth: [] - - basicAuth: [] - - jwtAuth: [] - responses: - "200": - content: - application/json: - schema: - type: array - items: - $ref: "#/components/schemas/Edge" - description: "" - post: - operationId: lineage_edges_create - tags: - - lineage - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/Edge" - application/x-www-form-urlencoded: - schema: - $ref: "#/components/schemas/Edge" - multipart/form-data: - schema: - $ref: "#/components/schemas/Edge" - required: true - security: - - cookieAuth: [] - - tokenAuth: [] - - basicAuth: [] - - jwtAuth: [] - responses: - "201": - content: - application/json: - schema: - $ref: "#/components/schemas/Edge" - description: "" - /api/v1/lineage/edges/{id}/: - get: - operationId: lineage_edges_retrieve - parameters: - - in: path - name: id - schema: - type: string - format: uuid - description: A UUID string identifying this edge. - required: true - tags: - - lineage - security: - - cookieAuth: [] - - tokenAuth: [] - - basicAuth: [] - - jwtAuth: [] - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/Edge" - description: "" - put: - operationId: lineage_edges_update - parameters: - - in: path - name: id - schema: - type: string - format: uuid - description: A UUID string identifying this edge. - required: true - tags: - - lineage - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/Edge" - application/x-www-form-urlencoded: - schema: - $ref: "#/components/schemas/Edge" - multipart/form-data: - schema: - $ref: "#/components/schemas/Edge" - required: true - security: - - cookieAuth: [] - - tokenAuth: [] - - basicAuth: [] - - jwtAuth: [] - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/Edge" - description: "" - patch: - operationId: lineage_edges_partial_update - parameters: - - in: path - name: id - schema: - type: string - format: uuid - description: A UUID string identifying this edge. - required: true - tags: - - lineage - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/PatchedEdge" - application/x-www-form-urlencoded: - schema: - $ref: "#/components/schemas/PatchedEdge" - multipart/form-data: - schema: - $ref: "#/components/schemas/PatchedEdge" - security: - - cookieAuth: [] - - tokenAuth: [] - - basicAuth: [] - - jwtAuth: [] - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/Edge" - description: "" - delete: - operationId: lineage_edges_destroy - parameters: - - in: path - name: id - schema: - type: string - format: uuid - description: A UUID string identifying this edge. - required: true - tags: - - lineage - security: - - cookieAuth: [] - - tokenAuth: [] - - basicAuth: [] - - jwtAuth: [] - responses: - "204": - description: No response body - /api/v1/lineage/nodes/: - get: - operationId: lineage_nodes_list - tags: - - lineage - security: - - cookieAuth: [] - - tokenAuth: [] - - basicAuth: [] - - jwtAuth: [] - responses: - "200": - content: - application/json: - schema: - type: array - items: - $ref: "#/components/schemas/Node" - description: "" - post: - operationId: lineage_nodes_create - tags: - - lineage - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/Node" - application/x-www-form-urlencoded: - schema: - $ref: "#/components/schemas/Node" - multipart/form-data: - schema: - $ref: "#/components/schemas/Node" - required: true - security: - - cookieAuth: [] - - tokenAuth: [] - - basicAuth: [] - - jwtAuth: [] - responses: - "201": - content: - application/json: - schema: - $ref: "#/components/schemas/Node" - description: "" - /api/v1/lineage/nodes/{id}/: - get: - operationId: lineage_nodes_retrieve - parameters: - - in: path - name: id - schema: - type: string - format: uuid - description: A UUID string identifying this node. - required: true - tags: - - lineage - security: - - cookieAuth: [] - - tokenAuth: [] - - basicAuth: [] - - jwtAuth: [] - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/Node" - description: "" - put: - operationId: lineage_nodes_update - parameters: - - in: path - name: id - schema: - type: string - format: uuid - description: A UUID string identifying this node. - required: true - tags: - - lineage - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/Node" - application/x-www-form-urlencoded: - schema: - $ref: "#/components/schemas/Node" - multipart/form-data: - schema: - $ref: "#/components/schemas/Node" - required: true - security: - - cookieAuth: [] - - tokenAuth: [] - - basicAuth: [] - - jwtAuth: [] - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/Node" - description: "" - patch: - operationId: lineage_nodes_partial_update - parameters: - - in: path - name: id - schema: - type: string - format: uuid - description: A UUID string identifying this node. - required: true - tags: - - lineage - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/PatchedNode" - application/x-www-form-urlencoded: - schema: - $ref: "#/components/schemas/PatchedNode" - multipart/form-data: - schema: - $ref: "#/components/schemas/PatchedNode" - security: - - cookieAuth: [] - - tokenAuth: [] - - basicAuth: [] - - jwtAuth: [] - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/Node" - description: "" - delete: - operationId: lineage_nodes_destroy - parameters: - - in: path - name: id - schema: - type: string - format: uuid - description: A UUID string identifying this node. - required: true - tags: - - lineage - security: - - cookieAuth: [] - - tokenAuth: [] - - basicAuth: [] - - jwtAuth: [] - responses: - "204": - description: No response body - /api/v1/memberships/: - get: - operationId: memberships_list - tags: - - memberships - security: - - cookieAuth: [] - - tokenAuth: [] - - basicAuth: [] - - jwtAuth: [] - responses: - "200": - content: - application/json: - schema: - type: array - items: - $ref: "#/components/schemas/Membership" - description: "" - /api/v1/memberships/{id}/: - get: - operationId: memberships_retrieve - parameters: - - in: path - name: id - schema: - type: string - format: uuid - description: A UUID string identifying this membership. - required: true - tags: - - memberships - security: - - cookieAuth: [] - - tokenAuth: [] - - basicAuth: [] - - jwtAuth: [] - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/Membership" - description: "" - /api/v1/runs/: - get: - operationId: runs_list - tags: - - runs - security: - - cookieAuth: [] - - tokenAuth: [] - - basicAuth: [] - - jwtAuth: [] - responses: - "200": - content: - application/json: - schema: - type: array - items: - $ref: "#/components/schemas/Run" - description: "" - /api/v1/runs/{id}/: - get: - operationId: runs_retrieve - parameters: - - in: path - name: id - schema: - type: string - required: true - tags: - - runs - security: - - cookieAuth: [] - - tokenAuth: [] - - basicAuth: [] - - jwtAuth: [] - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/Run" - description: "" - /api/v1/workspaces/: - get: - operationId: workspaces_list - tags: - - workspaces - security: - - cookieAuth: [] - - tokenAuth: [] - - basicAuth: [] - - jwtAuth: [] - responses: - "200": - content: - application/json: - schema: - type: array - items: - $ref: "#/components/schemas/Workspace" - description: "" - /api/v1/workspaces/{id}/: - get: - operationId: workspaces_retrieve - parameters: - - in: path - name: id - schema: - type: string - format: uuid - description: A UUID string identifying this workspace. - required: true - tags: - - workspaces - security: - - cookieAuth: [] - - tokenAuth: [] - - basicAuth: [] - - jwtAuth: [] - responses: - "200": - content: - application/json: - schema: - $ref: "#/components/schemas/Workspace" - description: "" - /schema/: - get: - operationId: schema_retrieve - description: |- - OpenApi3 schema for this API. Format can be selected via content negotiation. - - - YAML: application/vnd.oai.openapi - - JSON: application/vnd.oai.openapi+json - parameters: - - in: query - name: format - schema: - type: string - enum: - - json - - yaml - - in: query - name: lang - schema: - type: string - enum: - - af - - ar - - ar-dz - - ast - - az - - be - - bg - - bn - - br - - bs - - ca - - cs - - cy - - da - - de - - dsb - - el - - en - - en-au - - en-gb - - eo - - es - - es-ar - - es-co - - es-mx - - es-ni - - es-ve - - et - - eu - - fa - - fi - - fr - - fy - - ga - - gd - - gl - - he - - hi - - hr - - hsb - - hu - - hy - - ia - - id - - ig - - io - - is - - it - - ja - - ka - - kab - - kk - - km - - kn - - ko - - ky - - lb - - lt - - lv - - mk - - ml - - mn - - mr - - ms - - my - - nb - - ne - - nl - - nn - - os - - pa - - pl - - pt - - pt-br - - ro - - ru - - sk - - sl - - sq - - sr - - sr-latn - - sv - - sw - - ta - - te - - tg - - th - - tk - - tr - - tt - - udm - - uk - - ur - - uz - - vi - - zh-hans - - zh-hant - tags: - - schema - security: - - jwtAuth: [] - - cookieAuth: [] - - tokenAuth: [] - - {} - responses: - "200": - content: - application/vnd.oai.openapi: - schema: - type: object - additionalProperties: {} - application/yaml: - schema: - type: object - additionalProperties: {} - application/vnd.oai.openapi+json: - schema: - type: object - additionalProperties: {} - application/json: - schema: - type: object - additionalProperties: {} - description: "" -components: - schemas: - AuthToken: - type: object - properties: - username: - type: string - writeOnly: true - password: - type: string - writeOnly: true - token: - type: string - readOnly: true - required: - - password - - token - - username - Connection: - type: object - properties: - id: - type: string - format: uuid - readOnly: true - connector: - type: string - format: uuid - namespace: - type: string - maxLength: 255 - name: - type: string - maxLength: 255 - metadata: - type: object - additionalProperties: {} - is_active: - type: boolean - workspace: - type: string - format: uuid - required: - - connector - - id - - name - - workspace - Connector: - type: object - properties: - id: - type: string - format: uuid - readOnly: true - name: - type: string - maxLength: 255 - metadata: - type: object - additionalProperties: {} - is_active: - type: boolean - required: - - id - - name - Edge: - type: object - properties: - id: - type: string - format: uuid - readOnly: true - name: - type: string - display_name: - type: string - namespace: - type: string - maxLength: 255 - data_source: - type: string - maxLength: 255 - metadata: - type: object - additionalProperties: {} - is_active: - type: boolean - source: - type: string - format: uuid - destination: - type: string - format: uuid - required: - - data_source - - destination - - id - - source - Membership: - type: object - properties: - id: - type: string - format: uuid - readOnly: true - role: - $ref: "#/components/schemas/RoleEnum" - is_active: - type: boolean - user: - type: string - format: uuid - workspace: - type: string - format: uuid - required: - - id - - user - - workspace - Node: - type: object - properties: - id: - type: string - format: uuid - readOnly: true - namespace: - type: string - maxLength: 255 - name: - type: string - maxLength: 255 - display_name: - type: string - data_source: - type: string - maxLength: 255 - metadata: - type: object - additionalProperties: {} - is_active: - type: boolean - required: - - data_source - - id - - name - PatchedConnection: - type: object - properties: - id: - type: string - format: uuid - readOnly: true - connector: - type: string - format: uuid - namespace: - type: string - maxLength: 255 - name: - type: string - maxLength: 255 - metadata: - type: object - additionalProperties: {} - is_active: - type: boolean - workspace: - type: string - format: uuid - PatchedEdge: - type: object - properties: - id: - type: string - format: uuid - readOnly: true - name: - type: string - display_name: - type: string - namespace: - type: string - maxLength: 255 - data_source: - type: string - maxLength: 255 - metadata: - type: object - additionalProperties: {} - is_active: - type: boolean - source: - type: string - format: uuid - destination: - type: string - format: uuid - PatchedNode: - type: object - properties: - id: - type: string - format: uuid - readOnly: true - namespace: - type: string - maxLength: 255 - name: - type: string - maxLength: 255 - display_name: - type: string - data_source: - type: string - maxLength: 255 - metadata: - type: object - additionalProperties: {} - is_active: - type: boolean - RoleEnum: - enum: - - admin - - member - - read_only - type: string - Run: - type: object - properties: - id: - type: string - format: uuid - readOnly: true - connection: - type: string - format: uuid - status: - type: string - maxLength: 255 - metadata: - type: object - additionalProperties: {} - workspace: - type: string - format: uuid - user: - type: string - format: uuid - nullable: true - required: - - connection - - id - - status - - workspace - TokenObtainPair: - type: object - properties: - username: - type: string - writeOnly: true - password: - type: string - writeOnly: true - access: - type: string - readOnly: true - refresh: - type: string - readOnly: true - required: - - access - - password - - refresh - - username - TokenRefresh: - type: object - properties: - access: - type: string - readOnly: true - refresh: - type: string - writeOnly: true - required: - - access - - refresh - TokenVerify: - type: object - properties: - token: - type: string - writeOnly: true - required: - - token - Workspace: - type: object - properties: - id: - type: string - format: uuid - readOnly: true - name: - type: string - maxLength: 255 - required: - - id - - name - securitySchemes: - basicAuth: - type: http - scheme: basic - cookieAuth: - type: apiKey - in: cookie - name: sessionid - jwtAuth: - type: http - scheme: bearer - bearerFormat: JWT - tokenAuth: - type: apiKey - in: header - name: Authorization - description: Token-based authentication with required prefix "Token" diff --git a/docs/pages/api/server.mdx b/docs/pages/api/server.mdx deleted file mode 100644 index cc8c781f5..000000000 --- a/docs/pages/api/server.mdx +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: "Server API" -description: API Docs ---- - -// import { RedocStandalone } from 'redoc'; -// -// diff --git a/docs/pages/community.mdx b/docs/pages/community.mdx new file mode 100644 index 000000000..37567d451 --- /dev/null +++ b/docs/pages/community.mdx @@ -0,0 +1,25 @@ +--- +title: Community +description: Join the Grai Community +--- + +# Slack Channel + +Everyone is welcome on the community [slack channel](https://join.slack.com/t/graicommunity/shared_invite/zt-1il70kfeb-TaCm5fwHg_quWCpKNYyj6w). +It's a great place to ask questions, get support, and join a communtiy of like minded data professionals. + + + +# Discussions page + +We also maintain an active discussions page on [GitHub](https://github.com/orgs/grai-io/discussions) where you can ask questions, make suggestions, and get support. +We prioritize future integration development based on user feedback on the feature request page and are always looking for new ideas. + +## How to use the Discussions page + +Because we use GitHub issues exclusively for bug tracking we ask that you use the discussions page for all other questions and suggestions. +You can find links to a few different categories here or on the discussions page. + +* [**Feature Requests**](https://github.com/orgs/grai-io/discussions/categories/feature-requests) +* [**Documentation Requests**](https://github.com/orgs/grai-io/discussions/categories/documentation-requests) +* [**Q&A**](https://github.com/orgs/grai-io/discussions/categories/q-a) diff --git a/docs/pages/community/_meta.json b/docs/pages/community/_meta.json deleted file mode 100644 index 3dee7a663..000000000 --- a/docs/pages/community/_meta.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "slack": "Slack", - "contributor-guidelines": "Contributor Guidelines", - "clone-the-repo": "Clone the Repository", - "deployment": "Deployment & Testing", - "new-integrations": "New Integrations" -} diff --git a/docs/pages/community/slack.mdx b/docs/pages/community/slack.mdx deleted file mode 100644 index 786be1bdd..000000000 --- a/docs/pages/community/slack.mdx +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: "Community Slack" -description: Join the conversation! ---- - -# Join the Community - -Everyone is welcome on the community [slack channel](https://join.slack.com/t/graicommunity/shared_invite/zt-1il70kfeb-TaCm5fwHg_quWCpKNYyj6w). -It's a great place to ask questions, get support, and join a communtiy of like minded data professionals. diff --git a/docs/pages/concepts.mdx b/docs/pages/concepts.mdx new file mode 100644 index 000000000..f0568a3a1 --- /dev/null +++ b/docs/pages/concepts.mdx @@ -0,0 +1,16 @@ +--- +title: "Key Concepts" +description: Documentation around the core data concepts of Grai. +--- + +# Key Concepts + +There are four key concepts which will be helpful to understand before using Grai: + +* [Nodes](/concepts/nodes) +* [Edges](/concepts/edges) +* [Namespaces](/concepts/namespace) +* [Sources](/concepts/sources) + + +You'll find additional documentation about these and more here. diff --git a/docs/pages/community/contributor-guidelines.mdx b/docs/pages/contributing.mdx similarity index 100% rename from docs/pages/community/contributor-guidelines.mdx rename to docs/pages/contributing.mdx diff --git a/docs/pages/contributing/_meta.json b/docs/pages/contributing/_meta.json new file mode 100644 index 000000000..9e26dfeeb --- /dev/null +++ b/docs/pages/contributing/_meta.json @@ -0,0 +1 @@ +{} \ No newline at end of file diff --git a/docs/pages/community/clone-the-repo.mdx b/docs/pages/contributing/clone-the-repo.mdx similarity index 100% rename from docs/pages/community/clone-the-repo.mdx rename to docs/pages/contributing/clone-the-repo.mdx diff --git a/docs/pages/community/deployment.mdx b/docs/pages/contributing/deployment.mdx similarity index 97% rename from docs/pages/community/deployment.mdx rename to docs/pages/contributing/deployment.mdx index d4a6ff4f0..25b9b1b71 100644 --- a/docs/pages/community/deployment.mdx +++ b/docs/pages/contributing/deployment.mdx @@ -1,5 +1,5 @@ --- -title: "Deployment and testing" +title: "Deployment and Testing" description: Getting started with local testing --- @@ -60,7 +60,7 @@ applicable to the other python libraries and integrations. ### Installing a dev environment -Although all of our python libraries are installable through pip +Although all of our python libraries are directly installable through pip ```shell copy cd grai-core/grai-integrations/source-postgres diff --git a/docs/pages/community/new-integrations.mdx b/docs/pages/contributing/new-integrations.mdx similarity index 99% rename from docs/pages/community/new-integrations.mdx rename to docs/pages/contributing/new-integrations.mdx index a631e30ff..602f2d74b 100644 --- a/docs/pages/community/new-integrations.mdx +++ b/docs/pages/contributing/new-integrations.mdx @@ -1,5 +1,5 @@ --- -title: "Building new integrations" +title: "Building New Integrations" description: A guide to building new integrations tool integrations with Grai --- diff --git a/docs/pages/deployment.mdx b/docs/pages/deployment.mdx new file mode 100644 index 000000000..985dcd8fe --- /dev/null +++ b/docs/pages/deployment.mdx @@ -0,0 +1,33 @@ +--- +title: Deployment Guides +description: Covers the various deployment mechanisms available with Grai +--- + +import { Callout } from "nextra-theme-docs"; + +# Deployment + +Grai is generally deployed as a containerized application consisting of two core components. +Although building from source is possible, we recommend using the pre-built docker images. + +## Server + +- Postgres + Django +- Redis +- Celery + Celery Beat +- flower + +For more information about the server see [Grai Server](/server/). + +## Web App + +For more information about the web app see [Grai Web App](/web-app/) + +## Container Registry + +We maintain up to date docker images for all of the Grai services on GitHub's Container Registry `ghcr` + +| Service | Image | Tags | +| ------- | --------------------------------------- | -------------- | +| Server | ghcr.io/grai-io/grai-core/grai-server | latest, semver | +| Web App | ghcr.io/grai-io/grai-core/grai-frontend | latest, semver | diff --git a/docs/pages/deployment/kubernetes.mdx b/docs/pages/deployment/kubernetes.mdx new file mode 100644 index 000000000..d750bcf9a --- /dev/null +++ b/docs/pages/deployment/kubernetes.mdx @@ -0,0 +1,10 @@ +--- +title: Deploying Grai with Kubernetes +description: Deploying Grai with Kubernetes +--- + +# Kubernetes Introduction + +Grai works with Kubernetes out of the box. +We maintain deployment configurations for users deploying both with Helm and plain Kubernetes manifests / Kustomize. +You can find more information about both here. diff --git a/docs/pages/examples.mdx b/docs/pages/examples.mdx new file mode 100644 index 000000000..1721d9003 --- /dev/null +++ b/docs/pages/examples.mdx @@ -0,0 +1,9 @@ +--- +title: "Examples" +description: A collection of examples and guides for using Grai. +--- + +# Examples + +These pages cover examples and guides for using Grai. +If there are any specific examples you would like to see, please start a conversation on out documentation [requests page](https://github.com/orgs/grai-io/discussions/categories/documentation-requests) diff --git a/docs/pages/integrations.mdx b/docs/pages/integrations.mdx new file mode 100644 index 000000000..0b8123b26 --- /dev/null +++ b/docs/pages/integrations.mdx @@ -0,0 +1,22 @@ +--- +title: Grai Integrations +description: This section covers the various integrations supported by Grai +--- + + +# Introduction + +Although you can manually script the construction of Metadata for any application through combinations of the [REST API](/server/rest-api), [CLI](/tooling/cli), or [client library](/tooling/client) it's +more convenient which handle metadata extraction on your behalf. +Grai supports a number of integrations which can be used to automatically extract metadata from your application and which can be used both as standalone libraries or configured to run on the Web applicable + +## New Integrations + +We are constantly working on new integrations and if you have a specific integration you would like to see supported please create or vote on our [feature request page](https://github.com/orgs/grai-io/discussions/categories/feature-requests). + +If you would like to contribute a new integration you can find reference material for getting started [here](/contributing/new-integrations). + +### New Integration Support Policy + +As a matter of policy, once an integration has been accepted into the Grai repository the core team will accept responsibility for long term maintenance. +This means that we will ensure that the integration continues to work with the latest versions of Grai and that we will fix any bugs that are reported against the integration. diff --git a/docs/pages/server.mdx b/docs/pages/server.mdx new file mode 100644 index 000000000..0cebe2a25 --- /dev/null +++ b/docs/pages/server.mdx @@ -0,0 +1,45 @@ +--- +title: Grai Server Documentation +description: Everything you need to know about the Grai Server +--- + +# Grai Server + +## Introduction + +The Grai Server component is the core of the Grai platform. +It tracks the state of your data dependency graph, and executes jobs as needed to keep your data up to date. +With it you can schedule jobs like integration syncs to run on a regular basis, or trigger them manually. +It also tracks testing events called from your CI integrations. + +In addition to core data tracking the server backs both a [REST](/server/rest-api) and [GraphQL](/server/graphql-api) API and provides an admin console through which you can manage users on your Grai instance. + +## Dependencies + +Grai relies on the following background services. + +- [PostgresQL](https://www.postgresql.org/) as the core database +- [Redis](https://redis.com/) for cacheing +- [Celery](https://docs.celeryq.dev/en/stable/userguide/periodic-tasks.html) for job scheduling and worker execution +- [Flower](https://flower.readthedocs.io/en/latest/) for monitoring of Celery tasks +- [Django](https://www.djangoproject.com/) for our backend web framework + +You'll find the default admin login credentials below but these should be changed immediately in a production setting. + +```copy +username: null@grai.io +password: super_secret +``` + +## Admin + +For self-hosted users, the admin page can be accessed under the `/admin` route on your Grai instance. +For a default installation this would be `localhost:8000/admin`. +It is password protected and only accessible by superusers. + +The [Settings](/server/settings) page provides more information about configuring your own superuser but the default credentials are: + +```copy +username: null@grai.io +password: super_secret +``` diff --git a/docs/pages/server/_meta.json b/docs/pages/server/_meta.json index f43281089..84d423793 100644 --- a/docs/pages/server/_meta.json +++ b/docs/pages/server/_meta.json @@ -1,12 +1,10 @@ { - "index": "Background", + "settings": "Settings", "rest-api": { - "title": "Rest API", - "href": "https://api.grai.io/api/v1/schema/redoc/" + "title": "Rest API" }, "graphql-api": { - "title": "GraphQL API", - "href": "https://api.grai.io/graphql/" + "title": "GraphQL API" } } diff --git a/docs/pages/server/graphql-api.mdx b/docs/pages/server/graphql-api.mdx index c227f9748..e8f584b8e 100644 --- a/docs/pages/server/graphql-api.mdx +++ b/docs/pages/server/graphql-api.mdx @@ -5,4 +5,12 @@ description: Everything you need to know about the GraphQL API. # GraphQL API -Coming Soon. +The GraphQL API is the primary mechanism used by the web app to communicate with the server. +It is also available for use by third-party applications, however, it is prone to changing without notice. +If you need a stable interface for development you should use the [REST API](/server/rest-api/). + + +## GraphQL Playground + +We maintain a GraphQL Playground instance [here]("https://api.grai.io/graphql/"). +This is a great way to explore the API and test out queries and mutations. diff --git a/docs/pages/server/index.mdx b/docs/pages/server/index.mdx deleted file mode 100644 index 66f33eecf..000000000 --- a/docs/pages/server/index.mdx +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Server -description: Everything you need to know about the Grai Server ---- - -# Grai Server - -Grai relies on the following background services. - -- [PostgresQL](https://www.postgresql.org/) as the core database -- [Redis](https://redis.com/) for cacheing -- [Celery](https://docs.celeryq.dev/en/stable/userguide/periodic-tasks.html) for job scheduling and worker execution -- [Flower](https://flower.readthedocs.io/en/latest/) for monitoring of Celery tasks -- [Django](https://www.djangoproject.com/) for our backend web framework - -You'll find the default admin login credentials below but these should be changed immediately in a production setting. - -```copy -username: null@grai.io -password: super_secret -``` diff --git a/docs/pages/server/rest-api.mdx b/docs/pages/server/rest-api.mdx new file mode 100644 index 000000000..eda1f4f34 --- /dev/null +++ b/docs/pages/server/rest-api.mdx @@ -0,0 +1,50 @@ +--- +title: "REST API" +description: Everything you need to know about the REST API. +--- + +# REST API + +The REST API is supported primarily for third party applications. +It also back many of the secondary tools like the client library, cli, and some CI components like GitHub Actions. +If you need a stable interface for development this is the place to look + +## Authentication + +The REST API supports three authentication modes. + +* Basic Auth (username/password) +* API key Auth +* JWT Auth + +### Basic Auth + +Basic Auth is the simplest form of authentication. +It is supported by most HTTP clients and is easy to use. + +In order to use Basic Auth you will need to pass the username and password as the username and password of the HTTP request. + + +### API Key Auth + +Each API key is associated with an individual user and workspace. +In order to get started you'll need to first create an API key in the web app. +Once you have a key calls to the REST API will look for an `Api-Key` header with the value of your API key. +e.g. + +```bash +curl -X POST \ +-H "Authorization: Api-Key {your_api_key}" \ +-H "Content-Type: application/json; charset=utf-8" \ +... +``` + + +## REST Playground + +We maintain two playgrounds for the REST API alongside [openapi specs](https://api.grai.io/api/v1/schema/) for the most recent version of the API. + +* [**Redoc**](https://api.grai.io/api/v1/schema/redoc/) +* [**Swagger UI**](https://api.grai.io/api/v1/schema/swagger-ui/) + +In order to actually perform queries you will need to register on the cloud and authenticate against the API. diff --git a/docs/pages/tooling.mdx b/docs/pages/tooling.mdx new file mode 100644 index 000000000..0fd410c44 --- /dev/null +++ b/docs/pages/tooling.mdx @@ -0,0 +1,10 @@ +--- +title: Additional Components of Grai +description: This covers all the additional components of Grai outside of the core server and web application. +--- + + +# Tooling + +In addition to the core server and web application, Grai also provides a number of tools to help with development, testing, and scripting. +Each of these subtopics are covered in more detail below. diff --git a/docs/pages/web-app.mdx b/docs/pages/web-app.mdx new file mode 100644 index 000000000..20c904088 --- /dev/null +++ b/docs/pages/web-app.mdx @@ -0,0 +1,16 @@ +--- +title: Grai Web App Documentation +description: Everything you need to know about the Grai Web App +--- + +# Grai Web App + +## Introduction + +The Web App is the primary GUI component of Grai. +With it you can create and manage most components of Grai including adding new integrations, viewing your data dependency graph, creating new data sources, and more. + +## Dependencies + +The frontend is a [React](https://reactjs.org/) application written in [Typescript](https://www.typescriptlang.org/). +It communicates with the backend server through the [GraphQL API](/server/graphql-api). diff --git a/docs/pages/web-app/_meta.json b/docs/pages/web-app/_meta.json index b2f098de4..6114f2cf3 100644 --- a/docs/pages/web-app/_meta.json +++ b/docs/pages/web-app/_meta.json @@ -1,7 +1,4 @@ { - "index": { - "display": "hidden" - }, "getting-started": "Getting Started", "connections": "Connections", "users": "Users", diff --git a/docs/pages/web-app/index.mdx b/docs/pages/web-app/index.mdx deleted file mode 100644 index a82f4f0b9..000000000 --- a/docs/pages/web-app/index.mdx +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: Web App -description: Everything you need to know about the Grai Web App ---- - -# Web App - -The frontend is [Typescript](https://www.typescriptlang.org/) and [React](https://reactjs.org/). -It communicates with the backend server through the [GraphQL API](/server/graphql-api).