Docs improvements (#29)

Author: arkjedrz

README.md

@@ -3,61 +3,13 @@
 `zxc` is a directory-oriented command runner.
 This means it is able to run commands defined by YAML files.
 
-## Basics of operation
+## Features
 
-### Definition files location
+- YAML-based definition - human-readable and easy to write
+- Jinja-based template substitution - flexible
+- native look and feel
 
-Definition files are searched for in two places:
-
-- local - from CWD.
-- external - from `$HOME/.zxc/<mirrored CWD path>`.
-E.g., if CWD is `/opt/app/` then `$HOME/.zxc/opt/app/` should be used.
-
-Following file names are allowed:
-
-- `.zxc.yml`
-- `.zxc.yaml`
-- `zxc.yml`
-- `zxc.yaml`
-
-It's expected that at least one definition file is found.
-It's not allowed to have multiple definition files in one directory.
-
-External definition file takes precedence.
-This might cause command to be overwritten if defined in both files.
-
-### Definition file
-
-#### Defining a command
-
-Following fields are used to define a command:
-
-- command name is used as a key
-- `command` - shell command to run - mandatory
-- `description` - description - optional
-- `arguments` - arguments - optional
-
-#### Defining an argument
-
-Following fields are used to define an argument:
-
-- argument name is used as a key
-- `flags` - list of flags - mandatory
-  - named arguments contain flags starting with `-` and/or `--`:
-    - multiple short/long flags cannot be defined for the same argument
-    - 1 or 2 flags are expected
-  - positional arguments contain flag not starting with `-` or `--`.
-  - argument cannot be simultanously named and positional
-- `default` - default value - optional
-  - argument is considered required if default value is not specified
-- `description` - description - optional
-
-### Argument substitution
-
-Jinja is used as a template engine.
-`command` field can contain double curly braces to provide arguments to the command.
-
-### Example
+## Example
 
 Simple definition file:
 
@@ -73,10 +25,37 @@ greet:
         Name to greet.
 ```
 
-Use following command to print `Hello John!`:
+Refer to [definition file documentation](./docs/definition_file.md) for more information.
+
+Use following command to print `Hello world!`:
 
 ```bash
-zxc greet --name John
+zxc greet --name world
+```
+
+![demo](./docs/demo.svg)
+
+## Installation
+
+### From source
+
+```bash
+cargo build --release
+cargo install --path .
+```
+
+### From packages
+
+`deb`-based systems:
+
+```bash
+sudo dpkg -i zxc_<version>-1_amd64.deb
+```
+
+`rpm`-based systems:
+
+```bash
+sudo rpm -i  zxc-<version>-1.x86_64.rpm
 ```
 
 ## Development
@@ -95,12 +74,12 @@ pre-commit install
 pre-commit run -a
 ```
 
-## Build and install
+### Build, test and install
 
 ```bash
 cargo build --release
-cargo install --path .
 cargo test
+cargo install --path .
 ```
 
 ### Create packages

docs/definition_file.md

@@ -0,0 +1,55 @@
+# Definition file
+
+This file contains description of definition file.
+
+## Location
+
+Definition files are searched for in two places:
+
+- local - from CWD.
+- external - from `$HOME/.zxc/<mirrored CWD path>`.
+E.g., if CWD is `/opt/app/` then `$HOME/.zxc/opt/app/` should be used.
+
+Following file names are allowed:
+
+- `.zxc.yml`
+- `.zxc.yaml`
+- `zxc.yml`
+- `zxc.yaml`
+
+It's expected that at least one definition file is found.
+It's not allowed to have multiple definition files in one directory.
+
+External definition file takes precedence.
+This might cause command to be overwritten if defined in both files.
+
+## Structure
+
+### Defining a command
+
+Following fields are used to define a command:
+
+- command name is used as a key
+- `command` - shell command to run - mandatory
+- `description` - description - optional
+- `arguments` - arguments - optional
+
+### Defining an argument
+
+Following fields are used to define an argument:
+
+- argument name is used as a key
+- `flags` - list of flags - mandatory
+  - named arguments contain flags starting with `-` and/or `--`:
+    - multiple short/long flags cannot be defined for the same argument
+    - 1 or 2 flags are expected
+  - positional arguments contain flag not starting with `-` or `--`.
+  - argument cannot be simultanously named and positional
+- `default` - default value - optional
+  - argument is considered required if default value is not specified
+- `description` - description - optional
+
+### Argument substitution
+
+Jinja is used as a template engine.
+`command` field can contain double curly braces to provide arguments to the command.

docs/demo.cast

@@ -0,0 +1,71 @@
+{"version": 2, "width": 120, "height": 39, "timestamp": 1751715824, "idle_time_limit": 1.0, "env": {"SHELL": "/bin/bash", "TERM": "tmux-256color"}}
+[0.044619, "o", "\u001b[?2004h$ "]
+[4.027023, "o", "c"]
+[4.093216, "o", "a"]
+[4.296752, "o", "t"]
+[4.408683, "o", " "]
+[4.657105, "o", "."]
+[4.859715, "o", "z"]
+[4.926795, "o", "x"]
+[5.336817, "o", "c.yml "]
+[6.186706, "o", "\r\n\u001b[?2004l\r"]
+[6.188329, "o", "greet:\r\n  command: echo \"Hello {{ name }}!\"\r\n  description: Greets specified person.\r\n  arguments:\r\n    name:\r\n      flags: [\"-n\", \"--name\"]\r\n      default: User\r\n      description: |-\r\n        Name to greet.\r\n"]
+[6.188573, "o", "\u001b[?2004h$ "]
+[8.166947, "o", "z"]
+[8.278424, "o", "x"]
+[8.346726, "o", "c"]
+[8.481338, "o", " "]
+[8.638277, "o", "-"]
+[8.818965, "o", "-"]
+[9.021692, "o", "h"]
+[9.111704, "o", "e"]
+[9.381747, "o", "l"]
+[9.425991, "o", "p"]
+[9.921486, "o", "\r\n\u001b[?2004l\r"]
+[9.923387, "o", "`zxc` is a directory-oriented command runner.\r\nThis means it is able to run commands defined by YAML files.\r\n\r\n\u001b[1m\u001b[4mUsage:\u001b[0m \u001b[1mzxc\u001b[0m <COMMAND>\r\n\r\n\u001b[1m\u001b[4mCommands:\u001b[0m\r\n  \u001b[1mgreet\u001b[0m  Greets specified person.\r\n         \r\n         Command: echo \"Hello {{ name }}!\"\r\n  \u001b[1mhelp\u001b[0m   Print this message or the help of the given subcommand(s)\r\n\r\n\u001b[1m\u001b[4mOptions:\u001b[0m\r\n  \u001b[1m-h\u001b[0m, \u001b[1m--help\u001b[0m     Print help\r\n  \u001b[1m-V\u001b[0m, \u001b[1m--version\u001b[0m  Print version\r\n"]
+[9.92379, "o", "\u001b[?2004h$ "]
+[11.42907, "o", "z"]
+[11.518818, "o", "x"]
+[11.586331, "o", "c"]
+[11.946921, "o", " "]
+[12.711525, "o", "g"]
+[12.913782, "o", "r"]
+[12.958654, "o", "e"]
+[13.16194, "o", "e"]
+[13.230291, "o", "t"]
+[13.386404, "o", " "]
+[13.566821, "o", "-"]
+[13.746714, "o", "-"]
+[13.926738, "o", "h"]
+[14.017638, "o", "e"]
+[14.242104, "o", "l"]
+[14.286895, "o", "p"]
+[15.096697, "o", "\r\n\u001b[?2004l\r"]
+[15.098556, "o", "Greets specified person.\r\n\r\nCommand: echo \"Hello {{ name }}!\"\r\n\r\n\u001b[1m\u001b[4mUsage:\u001b[0m \u001b[1mzxc greet\u001b[0m [OPTIONS]\r\n\r\n\u001b[1m\u001b[4mOptions:\u001b[0m\r\n  \u001b[1m-n\u001b[0m, \u001b[1m--name\u001b[0m <name>  Name to greet. [default: User]\r\n  \u001b[1m-h\u001b[0m, \u001b[1m--help\u001b[0m         Print help\r\n"]
+[15.098963, "o", "\u001b[?2004h$ "]
+[17.616816, "o", "z"]
+[17.706205, "o", "x"]
+[17.774051, "o", "c"]
+[17.886288, "o", " "]
+[18.066419, "o", "g"]
+[18.493719, "o", "r"]
+[18.606244, "o", "e"]
+[18.789977, "o", "e"]
+[18.898924, "o", "t"]
+[19.011787, "o", " "]
+[19.326664, "o", "-"]
+[19.461633, "o", "-"]
+[19.641949, "o", "n"]
+[19.687082, "o", "a"]
+[19.821206, "o", "m"]
+[19.888955, "o", "e"]
+[20.002023, "o", " "]
+[20.969084, "o", "w"]
+[21.058765, "o", "o"]
+[21.486245, "o", "r"]
+[21.598832, "o", "l"]
+[21.711747, "o", "d"]
+[22.206956, "o", "\r\n\u001b[?2004l\r"]
+[22.210662, "o", "Hello world!\r\n"]
+[22.21135, "o", "\u001b[?2004h$ "]
+[23.826833, "o", "\u001b[?2004l\r\r\nexit\r\n"]