refactor: move docs to this repository (#317)

.circleci/config.yml

@@ -1,10 +1,11 @@
 version: 2.1
 
 orbs:
- sdk: ory/[email protected].27
- changelog: ory/[email protected].6
+ sdk: ory/[email protected].33
+ changelog: ory/[email protected].9
  goreleaser: ory/[email protected]
  nancy: ory/[email protected]
+ docs: ory/[email protected]
  golangci: ory/[email protected]
 
 jobs:
@@ -94,6 +95,15 @@ workflows:
  only: /.*/
  branches:
  ignore: /master/
+ - docs/build:
+ requires:
+ - test
+ - golangci/lint
+ filters:
+ tags:
+ only: /.*/
+ branches:
+ only: master
  - sdk/release:
  requires:
  - test

docs/api.swagger.json → .schema/api.swagger.json

@@ -1087,7 +1087,7 @@
  ],
  "properties": {
  "action": {
- "description": "Action should be used as the form action URL (\u003cform action=\"{{ .Action }}\" method=\"post\"\u003e).",
+ "description": "Action should be used as the form action URL `\u003cform action=\"{{ .Action }}\" method=\"post\"\u003e`.",
  "type": "string"
  },
  "errors": {
@@ -1116,7 +1116,7 @@
  ],
  "properties": {
  "disabled": {
- "description": "Disabled is the equivalent of \u003cinput disabled=\"{{.Disabled}}\"\u003e",
+ "description": "Disabled is the equivalent of `\u003cinput disabled=\"{{.Disabled}}\"\u003e`",
  "type": "boolean"
  },
  "errors": {
@@ -1127,23 +1127,23 @@
  }
  },
  "name": {
- "description": "Name is the equivalent of \u003cinput name=\"{{.Name}}\"\u003e",
+ "description": "Name is the equivalent of `\u003cinput name=\"{{.Name}}\"\u003e`",
  "type": "string"
  },
  "pattern": {
- "description": "Pattern is the equivalent of \u003cinput pattern=\"{{.Pattern}}\"\u003e",
+ "description": "Pattern is the equivalent of `\u003cinput pattern=\"{{.Pattern}}\"\u003e`",
  "type": "string"
  },
  "required": {
- "description": "Required is the equivalent of \u003cinput required=\"{{.Required}}\"\u003e",
+ "description": "Required is the equivalent of `\u003cinput required=\"{{.Required}}\"\u003e`",
  "type": "boolean"
  },
  "type": {
- "description": "Type is the equivalent of \u003cinput type=\"{{.Type}}\"\u003e",
+ "description": "Type is the equivalent of `\u003cinput type=\"{{.Type}}\"\u003e`",
  "type": "string"
  },
  "value": {
- "description": "Value is the equivalent of \u003cinput value=\"{{.Value}}\"\u003e",
+ "description": "Value is the equivalent of `\u003cinput value=\"{{.Value}}\"\u003e`",
  "type": "object"
  }
  }
@@ -1287,7 +1287,7 @@
  ],
  "properties": {
  "action": {
- "description": "Action should be used as the form action URL (\u003cform action=\"{{ .Action }}\" method=\"post\"\u003e).",
+ "description": "Action should be used as the form action URL `\u003cform action=\"{{ .Action }}\" method=\"post\"\u003e`.",
  "type": "string"
  },
  "errors": {
@@ -1416,7 +1416,7 @@
  ],
  "properties": {
  "action": {
- "description": "Action should be used as the form action URL (\u003cform action=\"{{ .Action }}\" method=\"post\"\u003e).",
+ "description": "Action should be used as the form action URL `\u003cform action=\"{{ .Action }}\" method=\"post\"\u003e`.",
  "type": "string"
  },
  "errors": {

docs/config.schema.json → .schema/config.schema.json

@@ -1,5 +1,5 @@
 {
- "$id": "https:/ory/kratos/docs/config.schema.json",
+ "$id": "https:/ory/kratos/.schema/config.schema.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "ORY Kratos Configuration",
  "type": "object",

Makefile

@@ -67,14 +67,14 @@ test: test-resetdb
 # Generates the SDKs
 .PHONY: sdk
 sdk:
- $$(go env GOPATH)/bin/swagger generate spec -m -o docs/api.swagger.json -x internal/httpclient
- $$(go env GOPATH)/bin/swagutil sanitize ./docs/api.swagger.json
- $$(go env GOPATH)/bin/swagger validate ./docs/api.swagger.json
- $$(go env GOPATH)/bin/swagger flatten --with-flatten=remove-unused -o ./docs/api.swagger.json ./docs/api.swagger.json
- $$(go env GOPATH)/bin/swagger validate ./docs/api.swagger.json
+ $$(go env GOPATH)/bin/swagger generate spec -m -o .schema/api.swagger.json -x internal/httpclient
+ $$(go env GOPATH)/bin/swagutil sanitize ./.schema/api.swagger.json
+ $$(go env GOPATH)/bin/swagger validate ./.schema/api.swagger.json
+ $$(go env GOPATH)/bin/swagger flatten --with-flatten=remove-unused -o ./.schema/api.swagger.json ./.schema/api.swagger.json
+ $$(go env GOPATH)/bin/swagger validate ./.schema/api.swagger.json
  rm -rf internal/httpclient
  mkdir -p internal/httpclient
- $$(go env GOPATH)/bin/swagger generate client -f ./docs/api.swagger.json -t internal/httpclient -A Ory_Kratos
+ $$(go env GOPATH)/bin/swagger generate client -f ./.schema/api.swagger.json -t internal/httpclient -A Ory_Kratos
  make format
 
 quickstart:

README.md

@@ -1,4 +1,4 @@
-<h1 align="center"><img src="./docs/images/banner_kratos.png" alt="ORY Kratos - Cloud native Identity and User Management"></h1>
+<h1 align="center"><img src=".github/banner_kratos.png" alt="ORY Kratos - Cloud native Identity and User Management"></h1>
 
 <h4 align="center">
  <a href="https://www.ory.sh/chat">Chat</a> |

cmd/serve.go

@@ -51,7 +51,7 @@ DON'T DO THIS IN PRODUCTION!
  },
 }
 
-var schemas = packr.New("schemas", "../docs")
+var schemas = packr.New("schemas", "../.schema")
 
 func init() {
  rootCmd.AddCommand(serveCmd)

docs/.editorconfig

@@ -0,0 +1,8 @@
+root = true
+
+[*]
+insert_final_newline = true
+charset = utf-8
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 2

docs/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

docs/.prettierignore

@@ -0,0 +1,6 @@
+build/
+website/build/
+schemas/
+apis/
+.widdershins/
+hooks/

docs/.prettierrc

@@ -0,0 +1,5 @@
+{
+ "proseWrap": "always",
+ "singleQuote": true,
+ "trailingComma": "es5"
+}

docs/.widdershins/config.json

@@ -0,0 +1,20 @@
+{
+ "language_tabs": [],
+ "verbose": true,
+ "codeSamples": true,
+ "httpSnippet": true,
+ "search": false,
+ "discovery": false,
+ "tocSummary": true,
+ "sample": true,
+ "tagGroups": [
+ {
+ "title": "Public Endpoints",
+ "tags": ["public"]
+ },
+ {
+ "title": "Administrative Endpoints",
+ "tags": ["admin"]
+ }
+ ]
+}

docs/.widdershins/templates/README.md

@@ -0,0 +1,72 @@
+## Swagger / OpenAPI 2 and OpenAPI 3 template parameters
+
+Note that properties of OpenAPI objects will be in OpenAPI 3.0 form, as Swagger
+/ OpenAPI 2.0 definitions are converted automatically.
+
+### Code templates
+
+- `method` - the HTTP method of the operation (in lower-case)
+- `methodUpper` - the HTTP method of the operation (in upper-case)
+- `url` - the full URL of the operation (including protocol and host)
+- `consumes[]` - an array of MIME-types the operation consumes
+- `produces[]` - an array of MIME-types the operation produces
+- `operation` - the current operation object
+- `operationId` - the current operation id
+- `opName` - the operationId if set, otherwise the method + path
+- `tags[]` - the full list of tags applying to the operation
+- `security` - the security definitions applying to the operation
+- `resource` - the current tag/path object
+- `parameters[]` - an array of parameters for the operation (see below)
+- `queryString` - an example queryString, urlEncoded
+- `requiredQueryString` - an example queryString for `required:true` parameters
+- `queryParameters[]` - a subset of `parameters` that are `in:query`
+- `requiredParameters[]` - a subset of `queryParameters` that are
+ `required:true`
+- `headerParameters[]` - a subset of `parameters` that are `in:header`
+- `allHeaders[]` - a concatenation of `headerParameters` and pseudo-parameters
+ `Accept` and `Content-Type`, and optionally `Authorization` (the latter has an
+ `isAuth` boolean property set true so it can be omitted in templates if
+ desired
+
+### Parameter template
+
+- `parameters[]` - an array of
+ [parameters](https:/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#parameterObject),
+ including the following pseudo-properties
+ - `shortDesc` - a truncated version of the parameter description
+ - `safeType` - a computed version of the parameter type, including Body and
+ schema names
+ - `originalType` - the original type of the parameter
+ - `exampleValues` - an object containing examples for use in code-templates
+ - `json` - example values in JSON compatible syntax
+ - `object` - example values in raw object form (unquoted strings etc)
+ - `depth` - a zero-based indicator of the depth of expanded request body
+ parameters
+- `enums[]` - an array of (parameter)name/value pairs
+
+### Responses template
+
+- `responses[]` - an array of
+ [responses](https:/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#responseObject),
+ including `status` and `meaning` properties
+
+### Authentication template
+
+- `authenticationStr` - a simple string of methods (and scopes where
+ appropriate)
+- `securityDefinitions[]` - an array of applicable
+ [securityDefinitions](https:/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#securityRequirementObject)
+
+### Schema Property template
+
+- `schemaProperties[]` - an array of _ `name` _ `type` _ `required` _
+ `description`
+- `enums[]` - an array of (schema property)name/value pairs
+
+### Common to all templates
+
+- `openapi` - the top-level OpenAPI / Swagger document
+- `header` - the front-matter of the Slate/Shins markdown document
+- `host` - the (computed) host of the API
+- `protocol` - the default/first protocol of the API
+- `baseUrl` - the (computed) baseUrl of the API (including protocol and host)

docs/.widdershins/templates/authentication.def

@@ -0,0 +1,5 @@
+<aside class="warning">
+To perform this operation, you must be authenticated by means of one of the following methods:
+{{= data.utils.getAuthenticationStr(data) }}
+</aside>
+

docs/.widdershins/templates/authentication_none.def

@@ -0,0 +1,3 @@
+<aside class="success">
+This operation does not require authentication
+</aside>

docs/.widdershins/templates/callbacks.def

@@ -0,0 +1,38 @@
+{{? data.operation.callbacks}}
+
+#### Callbacks
+
+<div class="content well">
+
+{{ data.oldOperation = data.operation; }}
+
+{{ for (var c in data.operation.callbacks) { }}
+
+##### {{=c}}
+
+{{ var callback = data.operation.callbacks[c]; }}
+
+{{ for (var e in callback) { }}
+
+**{{=e}}**
+
+{{ var exp = callback[e]; }}
+
+{{ for (var m in exp) { }}
+
+{{ data.operation = exp[m]; }}
+{{ data.method.operation = data.operation; }}
+
+{{= data.templates.operation(data) }}
+
+{{ } /* of methods */ }}
+
+{{ } /* of expressions */ }}
+
+{{ } /* of callbacks */ }}
+
+{{ data.operation = data.oldOperation; }}
+
+</div>
+
+{{?}}

docs/.widdershins/templates/code_go.dot

@@ -0,0 +1,23 @@
+package main
+
+import (
+ "bytes"
+ "net/http"
+)
+
+func main() {
+
+{{?data.allHeaders.length}}
+ headers := map[string][]string{
+ {{~data.allHeaders :p:index}}"{{=p.name}}": []string{"{{=p.exampleValues.object}}"},
+ {{~}}
+ }{{?}}
+
+ data := bytes.NewBuffer([]byte{jsonReq})
+ req, err := http.NewRequest("{{=data.methodUpper}}", "{{=data.url}}", data)
+ req.Header = headers
+
+ client := &http.Client{}
+ resp, err := client.Do(req)
+ // ...
+}

docs/.widdershins/templates/code_http.dot

@@ -0,0 +1,7 @@
+{{=data.methodUpper}} {{=data.url}}{{=data.requiredQueryString}} HTTP/1.1{{? data.host}}
+Host: {{=data.host}}{{?}}{{?data.consumes.length}}
+Content-Type: {{=data.consumes[0]}}{{?}}{{?data.produces.length}}
+Accept: {{=data.produces[0]}}{{?}}
+{{?data.headerParameters.length}}{{~ data.headerParameters :p:index}}{{=p.name}}: {{=p.exampleValues.object}}
+{{~}}
+{{?}}

docs/.widdershins/templates/code_java.dot

@@ -0,0 +1,13 @@
+URL obj = new URL("{{=data.url}}{{=data.requiredQueryString}}");
+HttpURLConnection con = (HttpURLConnection) obj.openConnection();
+con.setRequestMethod("{{=data.methodUpper}}");
+int responseCode = con.getResponseCode();
+BufferedReader in = new BufferedReader(
+ new InputStreamReader(con.getInputStream()));
+String inputLine;
+StringBuffer response = new StringBuffer();
+while ((inputLine = in.readLine()) != null) {
+ response.append(inputLine);
+}
+in.close();
+System.out.println(response.toString());

docs/.widdershins/templates/code_javascript.dot

@@ -0,0 +1,14 @@
+{{?data.allHeaders.length}}var headers = {
+{{~data.allHeaders :p:index}} '{{=p.name}}':{{=p.exampleValues.json}}{{?index < data.allHeaders.length-1}},{{?}}
+{{~}}
+};
+{{?}}
+$.ajax({
+ url: '{{=data.url}}',
+ method: '{{=data.method.verb}}',
+{{?data.requiredQueryString}} data: '{{=data.requiredQueryString}}',{{?}}
+{{?data.allHeaders.length}} headers: headers,{{?}}
+ success: function(data) {
+ console.log(JSON.stringify(data));
+ }
+})