ci: add docs/cli job and validate docs formatting (#746)

Co-authored-by: aeneasr <3372410+aeneasr@users.noreply.github.com>

.circleci/config.yml

@@ -6,8 +6,8 @@ orbs:
   slack: circleci/slack@3.4.2
   sdk: ory/sdk@0.1.37
   nancy: ory/nancy@0.0.12
-  docs: ory/docs@0.0.4
-  golangci: ory/golangci@0.0.4
+  docs: ory/docs@0.0.8
+  golangci: ory/golangci@0.0.8
 
 jobs:
   test:
@@ -119,12 +119,23 @@ jobs:
             - "/go/pkg/mod"
       - run: ./test/e2e/run.sh << parameters.flavor >>
 
+  validate:
+    docker:
+      - image: circleci/golang:1.15-node
+        environment:
+          GO111MODULE: 'on'
+    working_directory: /go/src/github.com/ory/hydra
+    steps:
+      - checkout
+      - golangci/lint
+      - docs/check-format
+
 workflows:
   tbr:
     jobs:
       - nancy/test
       -
-        golangci/lint:
+        validate:
           filters:
             tags:
               only: /.*/
@@ -134,7 +145,7 @@ workflows:
           requires:
             - test
             - nancy/test
-            - golangci/lint
+            - validate
           filters:
             tags:
               only: /.*/
@@ -175,20 +186,28 @@ workflows:
             - test-e2e-postgres
             - test-e2e-mysql
             - test-e2e-cockroach
-            - golangci/lint
+            - validate
           filters:
             tags:
               only: /.*/
             branches:
               ignore: /master/
+      - docs/cli:
+          requires:
+            - test
+            - test-e2e-sqlite
+            - test-e2e-postgres
+            - test-e2e-mysql
+            - test-e2e-cockroach
+            - validate
       - docs/build:
           requires:
             - test
             - test-e2e-sqlite
             - test-e2e-postgres
             - test-e2e-mysql
             - test-e2e-cockroach
-            - golangci/lint
+            - validate
           filters:
             tags:
               only: /.*/
@@ -201,7 +220,7 @@ workflows:
             - test-e2e-postgres
             - test-e2e-mysql
             - test-e2e-cockroach
-            - golangci/lint
+            - validate
             - sdk/generate
             - goreleaser/release
           filters:
@@ -216,7 +235,7 @@ workflows:
             - test-e2e-postgres
             - test-e2e-mysql
             - test-e2e-cockroach
-            - golangci/lint
+            - validate
           filters:
             tags:
               only: /.*/
@@ -236,7 +255,7 @@ workflows:
             - test-e2e-postgres
             - test-e2e-mysql
             - test-e2e-cockroach
-            - golangci/lint
+            - validate
           filters:
             branches:
               ignore: /.*/

Makefile

@@ -24,6 +24,12 @@ endef
 $(foreach dep, $(GO_DEPENDENCIES), $(eval $(call make-go-dependency, $(dep))))
 $(call make-lint-dependency)
 
+.bin/clidoc:
+		go build -o .bin/clidoc ./cmd/clidoc/.
+
+docs/cli: .bin/clidoc
+		clidoc .
+
 .bin/traefik:
 		https://github.com/containous/traefik/releases/download/v2.3.0-rc4/traefik_v2.3.0-rc4_linux_amd64.tar.gz \
 			tar -zxvf traefik_${traefik_version}_linux_${arch}.tar.gz

docs/docs/cli/kratos-identities-delete.md

@@ -16,17 +16,12 @@ Delete identities by ID
 
 ### Synopsis
 
-This command deletes one or more identities by ID. To delete an identity by some
-selector, e.g. the recovery email address, use the list command in combination
-with jq. Example: delete the identity with the recovery email address
-"foo@bar.com":
+This command deletes one or more identities by ID. To delete an identity by some selector, e.g. the recovery email address, use the list command in combination with jq.
+Example: delete the identity with the recovery email address "foo@bar.com":
 
-kratos identities delete \$(kratos identities list --format json | jq -r
-'map(select(.recovery_addresses[].value == "foo@bar.com")) | .[].id')
+kratos identities delete \$(kratos identities list --format json | jq -r 'map(select(.recovery_addresses[].value == "foo@bar.com")) | .[].id')
 
-We have to admit, this is not easy if you don't speak jq fluently. What about
-opening an issue and telling us what predefined selectors you want to have?
-https://github.com/ory/kratos/issues/new/choose
+We have to admit, this is not easy if you don't speak jq fluently. What about opening an issue and telling us what predefined selectors you want to have? https://github.com/ory/kratos/issues/new/choose
 
 ```
 kratos identities delete <id-0 [id-1 ...]> [flags]
@@ -41,12 +36,11 @@ kratos identities delete <id-0 [id-1 ...]> [flags]
 ### Options inherited from parent commands
 
 ```
-  -e, --endpoint string   The upstream admin endpoint URL. Alternatively set using the KRATOS_ADMIN_ENDPOINT environmental variable.
+  -e, --endpoint string   The URL of ORY Kratos' Admin API. Alternatively set using the KRATOS_ADMIN_URL environmental variable.
   -f, --format string     Set the output format. One of table, json, and json-pretty.
   -q, --quiet             Prints only IDs, one per line. Takes precedence over --format.
 ```
 
 ### SEE ALSO
 
-- [kratos identities](kratos-identities) - Tools to interact with remote
-  identities
+- [kratos identities](kratos-identities) - Tools to interact with remote identities

docs/docs/cli/kratos-identities-get.md

@@ -16,17 +16,12 @@ Get one or more identities by ID
 
 ### Synopsis
 
-This command gets all the details about an identity. To get an identity by some
-selector, e.g. the recovery email address, use the list command in combination
-with jq. Example: get the identities with the recovery email address at the
-domain "ory.sh":
+This command gets all the details about an identity. To get an identity by some selector, e.g. the recovery email address, use the list command in combination with jq.
+Example: get the identities with the recovery email address at the domain "ory.sh":
 
-kratos identities get \$(kratos identities list --format json | jq -r
-'map(select(.recovery_addresses[].value | endswith("@ory.sh"))) | .[].id')
+kratos identities get \$(kratos identities list --format json | jq -r 'map(select(.recovery_addresses[].value | endswith("@ory.sh"))) | .[].id')
 
-We have to admit, this is not easy if you don't speak jq fluently. What about
-opening an issue and telling us what predefined selectors you want to have?
-https://github.com/ory/kratos/issues/new/choose
+We have to admit, this is not easy if you don't speak jq fluently. What about opening an issue and telling us what predefined selectors you want to have? https://github.com/ory/kratos/issues/new/choose
 
 ```
 kratos identities get <id-0 [id-1 ...]> [flags]
@@ -41,12 +36,11 @@ kratos identities get <id-0 [id-1 ...]> [flags]
 ### Options inherited from parent commands
 
 ```
-  -e, --endpoint string   The upstream admin endpoint URL. Alternatively set using the KRATOS_ADMIN_ENDPOINT environmental variable.
+  -e, --endpoint string   The URL of ORY Kratos' Admin API. Alternatively set using the KRATOS_ADMIN_URL environmental variable.
   -f, --format string     Set the output format. One of table, json, and json-pretty.
   -q, --quiet             Prints only IDs, one per line. Takes precedence over --format.
 ```
 
 ### SEE ALSO
 
-- [kratos identities](kratos-identities) - Tools to interact with remote
-  identities
+- [kratos identities](kratos-identities) - Tools to interact with remote identities

docs/docs/cli/kratos-identities-import.md

@@ -1,7 +1,7 @@
 ---
 id: kratos-identities-import
 title: kratos identities import
-description: kratos identities import import identities from files or STD_IN
+description: kratos identities import Import identities from files or STD_IN
 ---
 
 <!--
@@ -12,13 +12,19 @@ To improve this file please make your change against the appropriate "./cmd/*.go
 
 ## kratos identities import
 
-import identities from files or STD_IN
+Import identities from files or STD_IN
 
 ### Synopsis
 
-Import identities from files or STD_IN. Files are expected to each contain a
-single identity. The validity of files can be tested beforehand using
-`... identities validate`. Importing credentials is not yet supported.
+Import identities from files or STD_IN:
+
+    kratos identities import file.json
+
+    cat file.json | kratos identities import
+
+Files can contain only a single or an array of identities. The validity of files can be tested beforehand using "... identities validate".
+
+WARNING: Importing credentials is not yet supported.
 
 ```
 kratos identities import <file.json [file-2.json [file-3.json] ...]> [flags]
@@ -33,12 +39,11 @@ kratos identities import <file.json [file-2.json [file-3.json] ...]> [flags]
 ### Options inherited from parent commands
 
 ```
-  -e, --endpoint string   The upstream admin endpoint URL. Alternatively set using the KRATOS_ADMIN_ENDPOINT environmental variable.
+  -e, --endpoint string   The URL of ORY Kratos' Admin API. Alternatively set using the KRATOS_ADMIN_URL environmental variable.
   -f, --format string     Set the output format. One of table, json, and json-pretty.
   -q, --quiet             Prints only IDs, one per line. Takes precedence over --format.
 ```
 
 ### SEE ALSO
 
-- [kratos identities](kratos-identities) - Tools to interact with remote
-  identities
+- [kratos identities](kratos-identities) - Tools to interact with remote identities

docs/docs/cli/kratos-identities-list.md

@@ -31,12 +31,11 @@ kratos identities list [<page> <per-page>] [flags]
 ### Options inherited from parent commands
 
 ```
-  -e, --endpoint string   The upstream admin endpoint URL. Alternatively set using the KRATOS_ADMIN_ENDPOINT environmental variable.
+  -e, --endpoint string   The URL of ORY Kratos' Admin API. Alternatively set using the KRATOS_ADMIN_URL environmental variable.
   -f, --format string     Set the output format. One of table, json, and json-pretty.
   -q, --quiet             Prints only IDs, one per line. Takes precedence over --format.
 ```
 
 ### SEE ALSO
 
-- [kratos identities](kratos-identities) - Tools to interact with remote
-  identities
+- [kratos identities](kratos-identities) - Tools to interact with remote identities

docs/docs/cli/kratos-identities-patch.md

@@ -1,8 +1,7 @@
 ---
 id: kratos-identities-patch
 title: kratos identities patch
-description:
-  kratos identities patch Patch identities by ID (not yet implemented)
+description: kratos identities patch Patch identities by ID (not yet implemented)
 ---
 
 <!--
@@ -32,12 +31,11 @@ kratos identities patch <file.json [file-2.json [file-3.json] ...]> [flags]
 ### Options inherited from parent commands
 
 ```
-  -e, --endpoint string   The upstream admin endpoint URL. Alternatively set using the KRATOS_ADMIN_ENDPOINT environmental variable.
+  -e, --endpoint string   The URL of ORY Kratos' Admin API. Alternatively set using the KRATOS_ADMIN_URL environmental variable.
   -f, --format string     Set the output format. One of table, json, and json-pretty.
   -q, --quiet             Prints only IDs, one per line. Takes precedence over --format.
 ```
 
 ### SEE ALSO
 
-- [kratos identities](kratos-identities) - Tools to interact with remote
-  identities
+- [kratos identities](kratos-identities) - Tools to interact with remote identities

docs/docs/cli/kratos-identities-validate.md

@@ -16,10 +16,12 @@ Validate local identity files
 
 ### Synopsis
 
-Validate local identity files
+This command allows validation of identity files.
+It validates against the payload of the API and the identity schema as configured in Kratos.
+Identities can be supplied via STD_IN or JSON files containing a single or an array of identities.
 
 ```
-kratos identities validate  <file.json [file-2.json [file-3.json] ...]> [flags]
+kratos identities validate <file.json [file-2.json [file-3.json] ...]> [flags]
 ```
 
 ### Options
@@ -31,12 +33,11 @@ kratos identities validate  <file.json [file-2.json [file-3.json] ...]> [flags]
 ### Options inherited from parent commands
 
 ```
-  -e, --endpoint string   The upstream admin endpoint URL. Alternatively set using the KRATOS_ADMIN_ENDPOINT environmental variable.
+  -e, --endpoint string   The URL of ORY Kratos' Admin API. Alternatively set using the KRATOS_ADMIN_URL environmental variable.
   -f, --format string     Set the output format. One of table, json, and json-pretty.
   -q, --quiet             Prints only IDs, one per line. Takes precedence over --format.
 ```
 
 ### SEE ALSO
 
-- [kratos identities](kratos-identities) - Tools to interact with remote
-  identities
+- [kratos identities](kratos-identities) - Tools to interact with remote identities

docs/docs/cli/kratos-identities.md

@@ -21,7 +21,7 @@ Tools to interact with remote identities
 ### Options
 
 ```
-  -e, --endpoint string   The upstream admin endpoint URL. Alternatively set using the KRATOS_ADMIN_ENDPOINT environmental variable.
+  -e, --endpoint string   The URL of ORY Kratos' Admin API. Alternatively set using the KRATOS_ADMIN_URL environmental variable.
   -f, --format string     Set the output format. One of table, json, and json-pretty.
   -h, --help              help for identities
   -q, --quiet             Prints only IDs, one per line. Takes precedence over --format.
@@ -31,12 +31,8 @@ Tools to interact with remote identities
 
 - [kratos](kratos) -
 - [kratos identities delete](kratos-identities-delete) - Delete identities by ID
-- [kratos identities get](kratos-identities-get) - Get one or more identities by
-  ID
-- [kratos identities import](kratos-identities-import) - import identities from
-  files or STD_IN
+- [kratos identities get](kratos-identities-get) - Get one or more identities by ID
+- [kratos identities import](kratos-identities-import) - Import identities from files or STD_IN
 - [kratos identities list](kratos-identities-list) - List identities
-- [kratos identities patch](kratos-identities-patch) - Patch identities by ID
-  (not yet implemented)
-- [kratos identities validate](kratos-identities-validate) - Validate local
-  identity files
+- [kratos identities patch](kratos-identities-patch) - Patch identities by ID (not yet implemented)
+- [kratos identities validate](kratos-identities-validate) - Validate local identity files

docs/docs/cli/kratos-jsonnet-format.md

@@ -56,5 +56,4 @@ kratos jsonnet format path/to/files/*.jsonnet [more/files.jsonnet, [supports/**/
 
 ### SEE ALSO
 
-- [kratos jsonnet](kratos-jsonnet) - Helpers for linting and formatting JSONNet
-  code
+- [kratos jsonnet](kratos-jsonnet) - Helpers for linting and formatting JSONNet code

docs/docs/cli/kratos-jsonnet-lint.md

@@ -14,8 +14,7 @@ To improve this file please make your change against the appropriate "./cmd/*.go
 
 ### Synopsis
 
-Lints JSONNet files using the official JSONNet linter and exits with a status
-code of 1 when issues are detected.
+Lints JSONNet files using the official JSONNet linter and exits with a status code of 1 when issues are detected.
 
 Glob Syntax:
 
@@ -54,5 +53,4 @@ kratos jsonnet lint path/to/files/*.jsonnet [more/files.jsonnet, [supports/**/{f
 
 ### SEE ALSO
 
-- [kratos jsonnet](kratos-jsonnet) - Helpers for linting and formatting JSONNet
-  code
+- [kratos jsonnet](kratos-jsonnet) - Helpers for linting and formatting JSONNet code