Autogenerate CLI docs and sanitize README (#67)

We leverage https://pkg.go.dev/github.com/spf13/cobra/doc for
autogenerating CLI docs in markdown format. We also add github workflow
to make sure that up-to-date docs are also required to merge cli code
changes.

README was updated to have better structure and remove old info. Also we
now refer to cli with its correct name `outcli` in docs also.

NOTE: Even though we are now auto-generating docs, the comment/doc
strings in commands still need to be improved in a future PR.

Closes #46

.github/workflows/checks.yml

@@ -7,6 +7,21 @@ on:
       - main
 
 jobs:
+  cli-docs-up-to-date:
+    name: cli-docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version: '1.19'
+          cache: false
+      - name: Refresh CLI docs
+        run: go run internal/cli-docgen.go
+
+      - name: Verify whether CLI documentation is up-to-date
+        run: git diff --exit-code
+
   # Reference: https://github.com/golangci/golangci-lint-action
   golangci-lint:
     name: linting

README.md

@@ -2,37 +2,24 @@
 [![MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/ioki-mobility/go-outline/blob/main/LICENSE)
 
 # go-outline
+The module provides Go client and cli for [outline](https://www.getoutline.com/).
 
-Go client and cli for [outline](https://www.getoutline.com/).
+# Go Client
+The Go client provides easy to use API around [outline's official HTTP API](https://www.getoutline.com/developers).
 
-# Installation
-
-## Installing the client:
+## Installation
 ```shell
 go get github.com/ioki-mobility/go-outline
 ```
-
-## Installing the CLI:
-- Download pre-built binaries from [releases](https://github.com/ioki-mobility/go-outline/releases) page for your platform
-- Install via go toolchain:
-```shell
-go install github.com/ioki-mobility/go-outline/cli@latest
-```
-
-# Usage
-
-## Client
-
+## Usage Examples
 ### Create a client
-
 ```go
 cl := outline.New("https://server.url", &http.Client{}, "api key")
 ```
 
 > **Note**: You can create a new API key in your outline **account settings**.
 
 ### Get a collection
-
 ```go
 col, err := cl.Collections().Get("collection id").Do(context.Background())
 if err != nil {
@@ -41,9 +28,7 @@ if err != nil {
 fmt.Println(col)
 ```
 
-
 ### Get all collections
-
 ```go
 err := cl.Collections().List().Do(context.Background(), func(col *outline.Collection, err error) (bool, error) {
 	fmt.Println(col)
@@ -55,7 +40,6 @@ if err != nil {
 ```
 
 ### Create a collection
-
 ```go
 col, err := cl.Collections().Create("collection name").Do(context.Background()) 
 if err != nil {
@@ -76,7 +60,6 @@ colCreateClient.
 ```
 
 ### Document Create
-
 ```go
 doc := cl.Documents().Create("Document name", "collection id").Do(context.Background())
 ```
@@ -93,37 +76,14 @@ docCreateClient.
 	Do(context.Background())
 ```
 
-## CLI
 
-### Build the CLI
-
-```
-go build -o outline ./cli
-```
-
-### Required flags
-
-Any command requires the flags `server` and `key`.
-You can simply add them with `--server https://server.url` 
-and `--key sup3rS3cre7Ap1K3Y`.
-
-### Collections
-
-The basic command to work with collections is:
-```
-outline collections
-```
-
-#### Collections fetch
-
-To fetch a collection and display it in a json string use:
-```
-outline collections fetch [COLLECTION_ID] [flags]
+# CLI
+## Installation
+- Download pre-built binaries from [releases](https://github.com/ioki-mobility/go-outline/releases) page
+- Install via go toolchain:
+```shell
+go install github.com/ioki-mobility/go-outline/cli@latest
 ```
 
-#### Collections create
-
-To create a collection and display the created collection as a json string use:
-```
-outline collections create [COLLECTION_NAME] [flags]
-```
+## Usage
+[Latest cli docs.](./cli/docs/outcli.md)

cli/docs/outcli.md

@@ -0,0 +1,18 @@
+## outcli
+
+
+
+### Options
+
+```
+  -h, --help            help for outcli
+      --key string      The outline api key
+      --server string   The outline API server url
+```
+
+### SEE ALSO
+
+* [outcli collection](outcli_collection.md)	 - Work with collections
+* [outcli document](outcli_document.md)	 - Work with documents
+* [outcli version](outcli_version.md)	 - Show app version
+

cli/docs/outcli_collection.md

@@ -0,0 +1,29 @@
+## outcli collection
+
+Work with collections
+
+### Synopsis
+
+If you have to work with collection in any case, use this command
+
+### Options
+
+```
+  -h, --help   help for collection
+```
+
+### Options inherited from parent commands
+
+```
+      --key string      The outline api key
+      --server string   The outline API server url
+```
+
+### SEE ALSO
+
+* [outcli](outcli.md)	 - 
+* [outcli collection create](outcli_collection_create.md)	 - Creates a collection
+* [outcli collection docs](outcli_collection_docs.md)	 - Get document structure
+* [outcli collection info](outcli_collection_info.md)	 - Get collection info
+* [outcli collection list](outcli_collection_list.md)	 - List all collections
+

cli/docs/outcli_collection_create.md

@@ -0,0 +1,29 @@
+## outcli collection create
+
+Creates a collection
+
+### Synopsis
+
+Creates a collection with the given name and prints the result as json to stdout
+
+```
+outcli collection create [flags]
+```
+
+### Options
+
+```
+  -h, --help   help for create
+```
+
+### Options inherited from parent commands
+
+```
+      --key string      The outline api key
+      --server string   The outline API server url
+```
+
+### SEE ALSO
+
+* [outcli collection](outcli_collection.md)	 - Work with collections
+

cli/docs/outcli_collection_docs.md

@@ -0,0 +1,29 @@
+## outcli collection docs
+
+Get document structure
+
+### Synopsis
+
+Get a summary of associated documents (and children)
+
+```
+outcli collection docs [flags]
+```
+
+### Options
+
+```
+  -h, --help   help for docs
+```
+
+### Options inherited from parent commands
+
+```
+      --key string      The outline api key
+      --server string   The outline API server url
+```
+
+### SEE ALSO
+
+* [outcli collection](outcli_collection.md)	 - Work with collections
+

cli/docs/outcli_collection_info.md

@@ -0,0 +1,29 @@
+## outcli collection info
+
+Get collection info
+
+### Synopsis
+
+Get information about the collection
+
+```
+outcli collection info [flags]
+```
+
+### Options
+
+```
+  -h, --help   help for info
+```
+
+### Options inherited from parent commands
+
+```
+      --key string      The outline api key
+      --server string   The outline API server url
+```
+
+### SEE ALSO
+
+* [outcli collection](outcli_collection.md)	 - Work with collections
+

cli/docs/outcli_collection_list.md

@@ -0,0 +1,29 @@
+## outcli collection list
+
+List all collections
+
+### Synopsis
+
+Get a list of all collections.
+
+```
+outcli collection list [flags]
+```
+
+### Options
+
+```
+  -h, --help   help for list
+```
+
+### Options inherited from parent commands
+
+```
+      --key string      The outline api key
+      --server string   The outline API server url
+```
+
+### SEE ALSO
+
+* [outcli collection](outcli_collection.md)	 - Work with collections
+

cli/docs/outcli_document.md

@@ -0,0 +1,28 @@
+## outcli document
+
+Work with documents
+
+### Synopsis
+
+If you have to work with documents in any case, use this command
+
+### Options
+
+```
+  -h, --help   help for document
+```
+
+### Options inherited from parent commands
+
+```
+      --key string      The outline api key
+      --server string   The outline API server url
+```
+
+### SEE ALSO
+
+* [outcli](outcli.md)	 - 
+* [outcli document create](outcli_document_create.md)	 - Creates a document
+* [outcli document get](outcli_document_get.md)	 - Get an existing document by its ID
+* [outcli document update](outcli_document_update.md)	 - Update an existing document
+

cli/docs/outcli_document_create.md

@@ -0,0 +1,29 @@
+## outcli document create
+
+Creates a document
+
+### Synopsis
+
+Creates a collection with the given name and collection id
+
+```
+outcli document create [flags]
+```
+
+### Options
+
+```
+  -h, --help   help for create
+```
+
+### Options inherited from parent commands
+
+```
+      --key string      The outline api key
+      --server string   The outline API server url
+```
+
+### SEE ALSO
+
+* [outcli document](outcli_document.md)	 - Work with documents
+

cli/docs/outcli_document_get.md

@@ -0,0 +1,30 @@
+## outcli document get
+
+Get an existing document by its ID
+
+### Synopsis
+
+Get information about an existing document by specifying its document ID or a share ID
+
+```
+outcli document get [flags]
+```
+
+### Options
+
+```
+  -h, --help    help for get
+      --share   Treat the argument as document share iD
+```
+
+### Options inherited from parent commands
+
+```
+      --key string      The outline api key
+      --server string   The outline API server url
+```
+
+### SEE ALSO
+
+* [outcli document](outcli_document.md)	 - Work with documents
+