Generate docs/commands.md based on CLI help

This will significantly simplify the process of documentation updates.
Also, there is configured verification step which checks if
documentation is re-generated for fresh changes. This will guarantee
that we always will have up-to-date documentation for the commands
(most updated file).

#118

.wf/docs-generation.bash

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+
+export PATH=bin:${PATH}
+if [[ ! $(ls -l README.md) ]]; then
+    echo "Please run this script from the root of the repo."
+    echo "Current path: ${PWD}"
+    exit 1
+fi
+
+header() {
+    echo "# \`${1}\`"
+}
+
+report-command() {
+    header ${1} >> ${2}
+    eval "git-elegant ${1} --help" >> ${2}
+}
+
+report-commands() {
+    echo "Write all commands to '${1}'"
+    for command in $(git-elegant commands); do
+        report-command ${command} ${1}
+    done
+}
+
+escape-usage() {
+    local TMPFILE="TMPFILE"
+    local usage=""
+    local IFS=''
+    while read -r; do
+        if [[ ${REPLY} == usage* ]]; then
+            usage="found"
+        fi
+        if [[ ${usage} == "found" ]]; then
+            echo "\`\`\`bash" >> ${TMPFILE}
+            usage="close"
+        fi
+        if [[ -z ${REPLY} && ${usage} == "close" ]]; then
+            echo "\`\`\`" >> ${TMPFILE}
+            usage=""
+        fi
+        echo -e ${REPLY} >> ${TMPFILE}
+    done < ${1}
+    echo "Replace escaped file with original: '${TMPFILE}' > '${1}' "
+    rm -v ${1}
+    mv -v ${TMPFILE} ${1}
+}
+
+
+main() {
+    local final="docs/commands.md"
+    local commands="docs/raw-commands.md"
+    report-commands ${commands}
+    escape-usage ${commands}
+
+    echo "Craft '${final}' file  from '${commands}'"
+    header git-elegant > ${final}
+    echo "\`\`\`bash" >> ${final}
+    git-elegant >> ${final}
+    echo -e "\`\`\`\n" >> ${final}
+    cat ${commands} | sed -e '$ d' >> ${final}
+    rm -v ${commands}
+}
+
+main

README.md

@@ -54,7 +54,7 @@ something which should be quickly available, please propose changes here.
   - [Writing tests](#writing-tests)
   - [Assertions](#assertions)
   - [Test name template](#test-name-template)
-- [Documentation preview](#documentation-preview)
+- [Updating documentation](#updating-documentation)
 
 ### Architecture
 
@@ -131,7 +131,10 @@ Also, there are several optional addons which can be useful in some circumstance
 Use the following test name template - `'<command args>': <describe what will be tested>` like
 `'clone-repository': raise an error if cloneable URL isn't set`.
 
-### Documentation preview
+### Updating documentation
 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!
+
+The [docs/commands.md](docs/commands.md) generates by running `./.wf/docs-generation.bash` script.
+All other files in ["docs" directory](docs/) require manual corrections.