chore(examples): add more usage examples (#178)

Author: kangasta

…i/docs/generate_command_reference_nav.py .ci/docs/generate_dynamic_nav.py.ci/docs/generate_command_reference_nav.py renamed to .ci/docs/generate_dynamic_nav.py .ci/docs/generate_command_reference_nav.py renamed to .ci/docs/generate_dynamic_nav.py

@@ -8,7 +8,7 @@ def withBase(name, base):
 def parse_name(name):
     return name.replace('_', ' ').replace('.md', '').replace('index', '')
 
-def generateNav(path, base=''):
+def generateCommandsReferenceNav(path, base=''):
     pages = []
 
     for i in sorted(os.scandir(path), key=lambda i: parse_name(i.name)):
@@ -17,17 +17,27 @@ def generateNav(path, base=''):
             pages.append({withBase(name, base): i.path})
         if i.is_dir():
             name = i.name.replace('_', ' ')
-            pages.append({withBase(name, base): generateNav(i.path, base=name.replace('upctl ', ''))})
+            pages.append({withBase(name, base): generateCommandsReferenceNav(i.path, base=name.replace('upctl ', ''))})
 
     return pages
 
+def generateExamplesNav(path):
+    return [i.path for i in sorted(os.scandir(path), key=lambda i: i.name) if i.name != 'README.md']
+
+
 if __name__ == '__main__':
+    navs = dict()
+
     os.chdir('docs/')
-    nav = generateNav('commands_reference/')
+    navs["Commands reference"] = generateCommandsReferenceNav('commands_reference/')
+    navs["Examples"] = generateExamplesNav('examples/')
     os.chdir('..')
 
     with open("mkdocs.base.yaml") as f:
-        config = f.read().replace('Commands reference: []', f'Commands reference: {nav}')
-    
+        config = f.read()
+
+        for key, nav in navs.items():
+            config = config.replace(f'{key}: []', f'{key}: {nav}')
+
     with open("mkdocs.yaml", "w") as f:
         f.write(config)

.ci/docs/prepare_info_texts_for_mkdocs.py

@@ -0,0 +1,31 @@
+'''Prepare info texts for mkdocs
+
+This script overwrites code fences in the .md files copied into docs/examples so that only language and title are left in-place, because mkdocs (and the used theme) has limited support for fenced code-block info texts.
+'''
+import fileinput
+import os
+import re
+import sys
+
+def get_markdown_files(path):
+    return (f.path for f in os.scandir(path) if f.name.endswith('.md'))
+
+def simplify_info_texts(path):
+    for line in fileinput.input(path, inplace=True):
+        if line.startswith('```'):
+            start = re.search(r'^```[a-zA-Z]*', line)
+            title = re.search(r'title=".*"', line)
+
+            old = line.rstrip('\n')
+            new = f'{start.group(0)} {title.group(0)}' if title else f'{start.group(0)}'
+
+            if new != old:
+                sys.stderr.write(f'{fileinput.filename()}:{fileinput.filelineno()}:\n- {old}\n+ {new}\n')
+            print(new)
+        else:
+            print(line, end='')
+
+if __name__ == '__main__':
+    files = get_markdown_files('docs/examples/')
+    for f in files:
+        simplify_info_texts(f)

.gitignore

@@ -37,6 +37,7 @@ dist/
 
 # Generated docs content
 /docs/commands_reference/
+/docs/examples/
 /docs/CHANGELOG.md
 /mkdocs.yaml
 /site/

Makefile

@@ -38,11 +38,13 @@ build: fmt | $(BIN_DIR) ; $(info building executable for the current target…)
 clean-md-docs:
 	rm -f docs/changelog.md
 	rm -rf docs/commands_reference/
+	rm -rf docs/examples/
 
 .PHONY: md-docs
 md-docs: clean-md-docs ## Generate documentation (markdown)
 	$(GO) run ./.ci/docs/
 	cp CHANGELOG.md docs/changelog.md
+	cp -r examples/ docs/examples/
 
 .PHONY: clean-docs
 clean-docs:
@@ -55,7 +57,8 @@ install-docs-tools:
 
 .PHONY: docs
 docs: clean-docs md-docs install-docs-tools ## Generate documentation (mkdocs site)
-	$(PYTHON) .ci/docs/generate_command_reference_nav.py
+	$(PYTHON) .ci/docs/generate_dynamic_nav.py
+	$(PYTHON) .ci/docs/prepare_info_texts_for_mkdocs.py
 	mkdocs build
 
 .PHONY: build-all

README.md

@@ -178,30 +178,9 @@ Exit code | Description
 
 ## Examples
 
-Every command has a help and examples included and you can find all its options
-by adding `-h` at the end of the command, like `upctl network list -h`. Below,
-you'll find a few common commands that have many other available options as
-well.
+Every command has a `--help` parameter that can be used to print detailed usage instructions and examples on how to use the command. For example, run `upctl network list --help`, to display usage instructions and examples for `upctl network list` command.
 
-* Create a new server
-
-```bash
-upctl server create --hostname test-server.io --zone de-fra1 --ssh-keys ~/.ssh/id_rsa.pub
-```
-
-* Create storage
-
-```bash
-upctl storage create --size 25 --title test-storage --zone es-mad1
-```
-
-> Note: Storage size is in GB.
-
-* Attach storage to server
-
-```bash
-upctl server storage attach <SERVER-UUID> --storage <STORAGE-UUID>
-```
+See [examples](./examples/) directory for examples on more complex use-cases.
 
 ## Documentation
 

examples/README.md

@@ -0,0 +1,3 @@
+# Examples
+
+This directory contains examples on more complex `upctl` use-cases. As `upctl` is often used in scripts the examples also aim to parse values from machine readable outputs. This allows using the examples also as end-to-end test cases and makes them more copy-pasteable.

examples/create_a_custom_template.md

@@ -0,0 +1,71 @@
+# Create a custom template
+
+This example demonstrates how to create a custom template with `upctl`.
+
+To keep track of resources created during this example, we will use common prefix in all resource names.
+
+```env
+prefix=example-upctl-custom-template-
+```
+
+First, we will create server which disk will be used as a source for the custom template.
+
+```sh
+# Create ssh-key into current working directory
+ssh-keygen -t ed25519 -q -f "./id_ed25519" -N ""
+
+upctl server create \
+    --hostname ${prefix}source-server \
+    --zone pl-waw1 \
+    --ssh-keys ./id_ed25519.pub \
+    --network type=public \
+    --network type=utility \
+    --wait
+```
+
+After the server has started, you can connect to it and prepare the disk to be templatized. Then, to be able to templatize the storage disk, we will stop the server.
+
+```sh
+upctl server stop --type hard --wait ${prefix}source-server
+```
+
+The default name for the OS storage of servers created with `upctl` is `${server-title}-OS`, in this case `${prefix}source-server-OS`. We can use either that or the UUID of the storage, when creating the template. UUID of the storage can be printed, for example, by processing `json` output with jq.
+
+```sh
+upctl server show ${prefix}source-server -o json \
+    | jq -r ".storage[0].uuid"
+```
+
+Now we are ready for creating the template.
+
+```sh
+upctl storage templatise ${prefix}source-server-OS \
+    --title ${prefix}template \
+    --wait
+```
+
+Once the template is created, we can delete the source server 
+
+```sh
+upctl server delete ${prefix}source-server --delete-storages
+```
+
+To test that the template creation succeeded, create a new server from the just created template.
+
+```sh
+upctl server create \
+    --hostname ${prefix}server \
+    --zone pl-waw1 \
+    --network type=public \
+    --network type=utility \
+    --os ${prefix}template \
+    --wait
+```
+
+Finally, we can cleanup the created resources.
+
+```sh
+upctl server stop --type hard --wait ${prefix}server
+upctl server delete ${prefix}server --delete-storages
+upctl storage delete ${prefix}template
+```

examples/create_and_ssh_into_a_server.md

@@ -0,0 +1,47 @@
+# Create and ssh into a server
+
+This example demonstrates how to create a server with `upctl` and connect to the created server via ssh connection.
+
+To keep track of resources created during this example, we will use common prefix in all resource names.
+
+```env
+prefix=example-upctl-ssh-server-
+```
+
+In order to be able to connect to the server we are going to create, we will need an ssh-key. If you already have a ssh-key available, you can skip this step. The example creates the ssh-key into the current working directory, if you want to use this key for other authentication purposes as well, create the key into `~/.ssh` directory instead.
+
+```sh
+# Create ssh-key into current working directory
+ssh-keygen -t ed25519 -q -f "./id_ed25519" -N ""
+```
+
+Create a server using the above created ssh-key as login method.
+
+```sh
+upctl server create \
+    --hostname ${prefix}server \
+    --zone pl-waw1 \
+    --ssh-keys ./id_ed25519.pub \
+    --network type=public \
+    --network type=utility \
+    --wait
+```
+
+Find the IP address of the created server from the JSON output of `upctl server show` and execute hostname command via ssh connection on the created server.
+
+```sh
+# Parse public IP of the server with jq
+ip=$(upctl server show ${prefix}server -o json | jq -r '.networking.interfaces[] | select(.type == "public") | .ip_addresses[0].address')
+
+# Wait for a moment for the ssh server to become available
+sleep 15
+
+ssh -i id_ed25519 -o StrictHostKeyChecking=accept-new root@$ip "hostname"
+```
+
+Finally, we can cleanup the created resources.
+
+```sh
+upctl server stop --type hard --wait ${prefix}server
+upctl server delete ${prefix}server --delete-storages
+```

examples/possible_exit_codes.md

@@ -0,0 +1,46 @@
+# Possible exit codes
+
+`upctl` sets exit code based on number of failed tasks up to exit code 99. This example demonstrates executions with few different exit codes.
+
+To keep track of resources created during this example, we will use common prefix in all resource names.
+
+```env
+prefix=example-upctl-exit-codes-
+```
+
+Exit code 100 is set, for example, when command argument validation fails.
+
+```sh exit_code=100
+upctl server create
+# Error: required flag(s) "hostname", "zone" not set
+```
+
+Let's create two server and stop one of those to later see other failing exit codes. These command should succceed, and thus return zero exit code.
+
+```sh
+# Create ssh-key into current working directory
+ssh-keygen -t ed25519 -q -f "./id_ed25519" -N ""
+
+upctl server create --hostname ${prefix}vm-1 --zone pl-waw1 --ssh-keys ./id_ed25519.pub --wait
+upctl server create --hostname ${prefix}vm-2 --zone pl-waw1 --ssh-keys ./id_ed25519.pub --wait
+
+upctl server stop ${prefix}vm-1 --wait
+```
+
+Now let's try to stop both both of the created servers. Exit code will be one, as `${prefix}vm-1` is already stopped and thus cannot be stopped again. `${prefix}vm-2`, though, will be stopped as it was online. Thus one of the two operations failed.
+
+```sh exit_code=1
+upctl server stop ${prefix}vm-1 ${prefix}vm-2 --wait
+```
+
+If we now try to run above command again, exit code will be two as both of the servers are already stopped. Thus both stop operations failed.
+
+```sh exit_code=2
+upctl server stop ${prefix}vm-1 ${prefix}vm-2 --wait
+```
+
+Finally, we can cleanup the created resources.
+
+```sh
+upctl server delete ${prefix}vm-1 ${prefix}vm-2 --delete-storages
+```

mkdocs.base.yaml

@@ -13,6 +13,7 @@ extra_css:
 nav:
 - index.md
 - Commands reference: []
+- Examples: []
 - changelog.md
 
 theme:
@@ -29,3 +30,12 @@ theme:
 
 plugins:
 - search
+
+markdown_extensions:
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.superfences