docs: add documentation

README.md

@@ -22,19 +22,143 @@
   <b>Deno shell tools inspired by <a href="https://github.com/google/zx">zx</a></b>
 </p>
 
-## Global usage
+```typescript
+#!/usr/bin/env dzx
+/// <reference path="https://deno.land/x/dzx/types.d.ts" />
+
+console.log(`Hello from ${$.blue.bold("dzx")}!`);
 
-Install dzx globally
+const branch = await $`git branch --show-current`;
+await $`dep deploy --branch=${branch}`;
+
+await Promise.all([
+  $`deno lint --unstable`,
+  $`deno fmt --check`,
+  $`deno test --allow-all`,
+]);
+
+const name = "foo bar";
+await $`mkdir /tmp/${name}`;
+```
+
+## Content
+
+- [Install](#install)
+- [Documentation](#documentation)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Install
 
 ```
 deno install --allow-all -r -f https://deno.land/x/dzx/dzx.ts
 ```
 
-```typescript
-#!/usr/bin/env dzx
+## Documentation
+
+You can write your scripts in a file with .js, .mjs or .ts extension.
+
+Add next shebang at the beginning of your script:
+
+```
+#!/usr/bin/env zx
+```
+
+Now you will be able to run your script as:
+
+```shell
+chmod +x ./script.js
+./script.js
+```
+
+If you want to use typescript you need to add a tripple slash reference for the
+typings at the top of the file, but not before the shebang line.
+
+```
+#!/usr/bin/env zx
 /// <reference path="https://deno.land/x/dzx/types.d.ts" />
+```
+
+Now you will be able to run your typescript script the same way as your js
+script:
+
+```shell
+chmod +x ./script.ts
+./script.ts
+```
+
+You can also import all symbol directly from `dzx/mod.ts` instead of using
+globals.
+
+```ts
+#!/usr/bin/env zx
+import { $ } from "https://deno.land/x/dzx/mod.ts";
+```
+
+### `$.verbose`
+
+Enable debugging output.
+
+### `$.shell`
+
+Set the current shel.
+
+### `$.cwd`
+
+Set the current working directory.
+
+### $`command`
+
+```ts
+const count = parseInt(await $`ls -1 | wc -l`);
+console.log(`Files count: ${count}`);
+```
+
+#### Error Handling
+
+If the executed program returns a non-zero exit code, a `ProcessError` will be
+thrown.
+
+```ts
+try {
+  await $`exit 1`;
+} catch (p) {
+  console.log(`Exit code: ${p.exitCode}`);
+  console.log(`Error: ${p.stderr}`);
+}
+```
+
+#### `ProcessOutput`
 
-await $`Hello ${$.blue.bold("world")}!`;
+```ts
+class ProcessOutput {
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly statud: Deno.RunStatus;
+  toString(): string;
+}
+```
+
+#### `ProcessError`
+
+The `ProcessError` class extends from the `Error` class and implements all
+properties and methods from the `ProcessOutput`.
+
+```ts
+class ProcessError extends Error implements ProcessOutput {}
+```
+
+### `cd()`
+
+Global available cd method to set the current working directory. Also available
+on the global `$` symbol.
+
+### `$.[style]()`
+
+dzx has chainable color methods that are available on the global `$` symbol.
+
+```ts
+console.log($.blue("Hello world!"));
 ```
 
 ## Remote usage
@@ -43,5 +167,13 @@ await $`Hello ${$.blue.bold("world")}!`;
 #!/usr/bin/env deno run --allow-run --allow-read --allow-env https://deno.land/x/dzx/dzx.ts
 /// <reference path="https://deno.land/x/dzx/types.d.ts" />
 
-await $`Hello ${$.blue.bold("world")}!`;
+console.log(`Hello ${$.blue.bold("world")}!`);
 ```
+
+## Contributing
+
+Any kind of contribution is welcome!
+
+## License
+
+[MIT](LICENSE)