Polish documentation

"installation" and other related staffs have to be moved from README.md
to `docs` directory. The content of CONTRIBUTING.md is published on
README.md.

#140

README.md

@@ -1,33 +1,67 @@
-elegant-git
+Elegant git
 ===========
-Allows easy handle git tasks.
+"Elegant git" is an extension which simplifies daily routine with `git`. Please visit <https://elegant-git.bees-hive
+.org/> to read more.
 
 [![MIT license](http://img.shields.io/badge/license-MIT-brightgreen.svg)](https://github.com/bees-hive/elegant-git/blob/master/LICENSE)
 [![Build Status](https://travis-ci.org/bees-hive/elegant-git.svg?branch=master)](https://travis-ci.org/bees-hive/elegant-git)
 [![PDD status](http://www.0pdd.com/svg?name=bees-hive/elegant-git)](http://www.0pdd.com/p?name=bees-hive/elegant-git)
 
 [![Rultor.com](http://www.rultor.com/b/bees-hive/elegant-git)](http://www.rultor.com/p/bees-hive/elegant-git)
 
-Installation
-============
-bash
-----
-Run `curl https://raw.githubusercontent.com/bees-hive/elegant-git/master/install.bash | $(which bash)`
-to install the tool.
+## Contributing
 
-Run `rm -r ${HOME}/.elegant-git` if you need to remove the installation.
+### Coding rules
+We enforce having a consistent implementation by following the next strict rules:
+- add `#!/usr/bin/env bash` at the beginning of each script
+- use `boxtee` to execute each original `git` command 
 
-Homebrew
---------
-On macOS, you can install [Homebrew](https://brew.sh/) if you haven't already, then run:
-`brew install bees-hive/hive/elegant-git`
+### Debug mode
+You can enable debug mode by running `export GED=1` (the equivalent of `set -x` for `bash`). 
+Run `unset GED` to switch debug off. 
 
-To find out more [click here](https://github.com/bees-hive/homebrew-hive).
+### Testing procedure
+A testing procedure consists of 3 steps:
+1. unit testing using [bats](https://github.com/sstephenson/bats)
+2. installation testing
+3. validation of todo' correctness (for [0pdd](http://www.0pdd.com/p?name=bees-hive/elegant-git))
 
-Usage
-=====
-Run `git elegant` to see available commands.
+All these steps can be executed by
+`docker run -it --rm -v $PWD:/eg beeshive/elegant-git-ci:2 ./run-tests`.
 
-Development
-===========
-Please follow [CONTRIBUTING.md](CONTRIBUTING.md) when working with the code.
+`beeshive/elegant-git-ci` Docker image is also used on CI. If the image requires modifications,
+it has to be updated manually by the following instructions:
+1. update `Dockerfile` (including `version` and `description`)
+2. `docker build -t beeshive/elegant-git-ci:<version> .`
+3. `docker push beeshive/elegant-git-ci:<version>`
+
+### Unit testing
+#### Addons
+In order to have a working unit tests, you need to add `load addons-common` line to each `.bats`
+file. This addon configures right access to executables (`libexec` directory) and defines mandatory
+functions.
+
+Also, there are several optional addons which can be useful in some circumstances:
+- add `load addons-git`  to interact with real git repository
+- add `load addons-fake` to fake a Linux command
+- add `load addons-cd`   to fake `cd` command
+- add `load addons-read` to fake `read` command
+
+#### Writing tests
+1. **Use `setup()` or `teardown()`** bats methods only in the tests.
+2. Use **`check` instead of bats `run`** to execute a command to be tested.
+3. If `addons-fake` or `addons-git` is used, call `clean-fake` or `clean-git` within a `teardown()` method.
+
+#### Assertions
+- `[ "${lines[0]}" = "+ the space " ]` for a output line (index starts from 0)
+- `[ "$status" -eq 2 ]` for a command status
+- `[ "${#lines[@]}" -eq 0 ]` for an empty command output
+
+#### Test name template
+Use the following test name template - `'<command args>': <describe what will be tested>` like
+`'acquire-repository': raise an error if cloneable URL isn't set`.
+
+### Documentation preview
+In order to get the documentation preview locally, please install required dependencies with 
+`pip install -r docs/requirements.txt`. After, run `mkdocs serve` and open <http://127.0.0.1:8000/> 
+in a browser. That's it!

docs/commands.md

@@ -0,0 +1,53 @@
+`git elegant <command>` where `<command>` is one of
+
+- `feature`
+- `pull`
+- `push`
+- `push-after-rebase`
+- `rebase`
+- `init`
+- `acquire-repository`
+- `add`
+- `clear-local`
+- `configure-repository`
+- `check`
+- `save`
+
+# `feature`
+Creates a new branch based on `master`. If there are some uncommitted changes, they will be moved to the new branch.
+
+# `pull`
+Downloads new updates for a local branch.
+
+# `push`
+Upload current local branch to a remote one using `force` push. If the remote branch is absent, it will be created. Pushing to remote `master` isn't allowed.
+
+# `rebase`
+Reapplies commits on top of the latest `origin/master`.
+
+# `push-after-rebase`
+Executes [git elegant push](#push) after [git elegant rebase](#rebase).
+
+# `init`
+Creates an empty Git repository or reinitialize an existing one. Then runs local repository configuration.
+
+# `acquire-repository`
+Clone a repository into a new directory. Then runs local repository configuration.
+
+# `add`
+Adds file contents to the index interactively.
+
+# `clear-local`
+Removes all local branches which don't have remote tracking branches.
+
+# `configure-repository`
+Defines some settings for _local_ `git config`.
+
+# `check`
+Shows trailing whitespaces of uncommitted changes.
+
+# `commands`
+Displays all available commands.
+
+# `save`
+Saves the changes to the current branch as a commit.

docs/getting-started.md

@@ -0,0 +1,15 @@
+You can install "Elegant git" by either executing `bash` script or using `homebrew`. Please make
+sure you have completed all the provided instructions. After, just run `git elegant` to see all
+available commands or move to [commands](commands.md) page.
+
+# `bash` script
+Run `curl https://raw.githubusercontent.com/bees-hive/elegant-git/master/install.bash | $(which bash)`
+and follow the provided instructions to install the tool. `${HOME}/.elegant-git` directory will host
+all required files. That's why if you want to remove installation, you need to remove this directory
+only (`rm -r ${HOME}/.elegant-git`).  
+
+# Homebrew
+On macOS, you can install [Homebrew](https://brew.sh/) if you haven't already, then run
+`brew install bees-hive/hive/elegant-git`
+
+To find out more please visit <https://github.com/bees-hive/homebrew-hive>.

docs/index.md

@@ -1,60 +1,20 @@
-Elegant git
-===========
-`git elegant` is a `git` extension which allows simplifying of `git` interaction.
+# Overview
+"Elegant git" is an extension which simplifies daily routine with `git`. It encourages using of
+[GitHub flow](https://guides.github.com/introduction/flow/). However, you can try to apply it to
+your branching strategy as well.
 
-`git elegant` always says which original git command will be executed.
+# Philosophy
+- declarative interaction (usually each command consists of several `git` commands)
+- flat commits tree (no merge commits; `git rebase` instead of `git merge`) 
+- frozen main branch (disallow direct pushes to `master`)
 
-Philosophy
-----------
-- declarative interaction
-- no merge commits
-- no pushes to `master` branch
+In addition, "Elegant git" is always saying which original `git` commands were executed.
 
-Limitations
------------
+# Known limitations
 Support only one default remote - `origin`.
 
-Commands
---------
-### feature
-Creates a new branch based on `master`. If there are some uncommitted changes, they will be moved to the new branch.
+# Exit codes
+Usually "Elegant git" translates exit codes of original `git` commands. However, in some cases,
+it may face its own error and raises them as
 
-### pull
-Downloads new updates for a local branch.
-
-### push
-Upload current local branch to a remote one using `force` push. If the remote branch is absent, it will be created. Pushing to remote `master` isn't allowed.
-
-### rebase
-Reapplies commits on top of the latest `origin/master`.
-
-### push-after-rebase
-Executes [git elegant push](#push) after [git elegant rebase](#rebase).
-
-### init
-Creates an empty Git repository or reinitialize an existing one. Then runs local repository configuration.
-
-### acquire-repository
-Clone a repository into a new directory. Then runs local repository configuration.
-
-### add
-Adds file contents to the index interactively.
-
-### clear-local
-Removes all local branches which don't have remote tracking branches.
-
-### configure-repository
-Defines some settings for _local_ `git config`.
-
-### check
-Shows trailing whitespaces of uncommitted changes.
-
-### commands
-Displays all available commands.
-
-### save 
-Saves the changes to the current branch as a commit.
-
-Exit codes
-----------
-`81` - a philosophical constraint
+- `81` - a philosophical constraint

mkdocs.yml

@@ -6,6 +6,8 @@ repo_url: https://github.com/bees-hive/elegant-git
 theme: readthedocs
 nav:
   - Home: index.md
+  - Getting started: getting-started.md
+  - Commands: commands.md
   - License: licence.md
 
 copyright: Copyright &copy; 2019 <a href="https://extsoft.pro">Dmytro Serdiuk</a>, Maintained by <a href="https://github.com/bees-hive/elegant-git/graphs/contributors">project contributors</a>.