Merge pull request #41 from oasisprotocol/matevz/cli-examples

feat(docs): Add docs and example CLI usage

Author: matevz

.github/workflows/ci-tests.yml

@@ -43,3 +43,8 @@ jobs:
       - name: Run tests
         run: |
           make test
+      - name: Check examples
+        run: |
+          make clean-examples
+          make examples
+          git diff --exit-code examples

.markdownlint.yml

@@ -10,8 +10,19 @@ line-length:
   # Line length checking is not strict by default.
   strict: true
   line_length: 80
-  # Allow longer lines for code blocks.
-  code_block_line_length: 100
+  # Code blocks for examples are imported directly from the command output
+  # and do not have sensible max line length.
+  code_blocks: false
+
+# Front matter title (shown in the menu and doccards) may differ from the one
+# on the actual page.
+single-title:
+  front_matter_title: ""
+
+# Docusaurus uses custom {#some-title} syntax to define fragments (anchors), see:
+# https://docusaurus.io/docs/next/markdown-features/toc#heading-ids
+# Unfortunately, it is not compatible with the markdown linter yet.
+link-fragments: false
 
 # Do not always require language specifiers with fenced code blocks since they
 # are not part of the Markdown spec.

Makefile

@@ -1,5 +1,8 @@
 include common.mk
 
+# Each Oasis CLI example's input .in must have a corresponding output .out.
+EXAMPLES := $(patsubst %.in,%.out,$(wildcard examples/*/*.in))
+
 # Check if Go's linkers flags are set in common.mk and add them as extra flags.
 ifneq ($(GOLDFLAGS),)
 	GO_EXTRA_FLAGS += -ldflags $(GOLDFLAGS)
@@ -9,10 +12,20 @@ endif
 all: build
 
 # Build.
-build:
+build: oasis
+oasis: $(shell find . -name "*.go" -type f) go.sum go.mod
 	@$(PRINT) "$(MAGENTA)*** Building Go code...$(OFF)\n"
 	@$(GO) build -v -o oasis $(GOFLAGS) $(GO_EXTRA_FLAGS)
 
+examples: $(EXAMPLES)
+
+examples/%.out: examples/%.in oasis scripts/gen_example.sh
+	@rm -f $@
+	@scripts/gen_example.sh $< $@
+
+clean-examples:
+	@rm -f examples/*/*.out
+
 # Format code.
 fmt:
 	@$(PRINT) "$(CYAN)*** Running Go formatters...$(OFF)\n"
@@ -64,6 +77,8 @@ clean:
 # List of targets that are not actual files.
 .PHONY: \
 	all build \
+	examples \
+	clean-examples \
 	fmt \
 	$(lint-targets) lint \
 	$(test-targets) test \

README.md

@@ -31,7 +31,7 @@ in your `$PATH`.
 *NOTE: The rest of the README assumes the `oasis` binary is somewhere in your
 `$PATH`.*
 
-## Running
+## Quickstart
 
 You can interact with the Oasis CLI by invoking it from the command line as
 follows:
@@ -57,7 +57,7 @@ subcommand as follows:
 
 ```bash
 oasis network set-default testnet
-oasis paratime set-default testnet emerald
+oasis paratime set-default testnet sapphire
 ```
 
 To be able to sign transactions you will need to first create or import an
@@ -82,7 +82,13 @@ To show the account's balance on the default network/ParaTime, run:
 oasis account show
 ```
 
+The `account` command also allows you to transfer tokens, deposit or withdraw to
+and from ParaTimes, delegate your assets to validators etc.
+
+Check out the complete User's guide in [docs/README.md] and example invocations
+of the CLI in `examples` folder to learn more.
+
 ## Configuration
 
-All configuration is stored in the `$XDG_CONFIG_HOME/oasis` directory (defaults
-to `$HOME/.config/oasis`).
+All configuration is stored in the `$XDG_CONFIG_HOME/oasis` directory (e.g.
+`$HOME/.config/oasis` on Linux).

docs/README.md

@@ -0,0 +1,45 @@
+---
+title: Oasis CLI
+description: Powerful CLI for managing Oasis network, nodes, tokens and dapps
+---
+
+# Oasis Command Line Interface
+
+Oasis command-line interface (CLI) is a powerful all-in-one tool for
+interacting with the Oasis Network. You can download the latest release
+binaries from the [GitHub repository].
+
+It boasts a number of handy features:
+
+- Flexible setup:
+  - supports Mainnet, Testnet, Localnet or any other Oasis network deployment
+  - consensus layer configuration with arbitrary token
+  - configuration of custom ParaTimes with arbitrary token
+  - connecting to remote (via TCP/IP) or local (Unix socket) Oasis node
+    instance
+- Powerful wallet features:
+  - standard token operations (transfers, allowances, deposits, withdrawals and
+    balance queries)
+  - file-based wallet with password protection
+  - full Ledger hardware wallet support
+  - address book
+  - generation, signing and submitting transactions in non-interactive
+    (headless) mode
+  - offline transaction generation for air-gapped machines
+  - transaction encryption with X25519-Deoxys-II envelope
+  - support for Ed25519, Ethereum-compatible Secp256k1 and Sr25519 signature
+    schemes
+  - raw, BIP-44, ADR-8 and Ledger's legacy derivation paths
+- Node operator features:
+  - Oasis node inspection and healthchecks
+  - network governance transactions
+  - staking reward schedule transactions
+- Developer features:
+  - built-in testing accounts compatible with the Oasis test runner, the Oasis
+    CI and the official sapphire-dev and emerald-dev Docker images
+  - Oasis Wasm smart contract code deployment, instantiation, management and
+    calls
+  - debugging tools for deployed Wasm contracts
+  - inspection of blocks, transactions, results and events
+
+[GitHub repository]: https://github.com/oasisprotocol/cli/releases