From 1c6d8164cea42c328f0d8c6796e7e91f24fc9735 Mon Sep 17 00:00:00 2001
From: Dmytro Serdiuk <dmytro.serdiuk@gmail.com>
Date: Sun, 9 Feb 2020 23:29:52 +0200
Subject: [PATCH] Generate docs using Python instead of Bash

The reason for this change is that Bash script has unexpected failures
during execution in Docker on Mac. Also, as Python is already used, it
won't introduce updates to the CI environment.
---
 .workflows/ci-pipeline.bash     |  2 +-
 .workflows/docs-generation.bash | 65 ---------------------------------
 .workflows/docs.py              | 52 ++++++++++++++++++++++++++
 workflows                       |  2 +-
 4 files changed, 54 insertions(+), 67 deletions(-)
 delete mode 100755 .workflows/docs-generation.bash
 create mode 100644 .workflows/docs.py

diff --git a/.workflows/ci-pipeline.bash b/.workflows/ci-pipeline.bash
index a217bfe..1961220 100755
--- a/.workflows/ci-pipeline.bash
+++ b/.workflows/ci-pipeline.bash
@@ -31,7 +31,7 @@ pipeline() {
         --exclude=docs/*.png \
         --verbose --file=/dev/null                    || fail "Unreadable todo is identified."
     (
-        .workflows/docs-generation.bash
+        python .workflows/docs.py
         git update-index --really-refresh
         git diff-index --quiet HEAD --
     ) || fail "The documentation is not up to date. Please run './.workflows/docs-generation.bash' and commit the changes"
diff --git a/.workflows/docs-generation.bash b/.workflows/docs-generation.bash
deleted file mode 100755
index 7be4b2d..0000000
--- a/.workflows/docs-generation.bash
+++ /dev/null
@@ -1,65 +0,0 @@
-#!/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 show-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
diff --git a/.workflows/docs.py b/.workflows/docs.py
new file mode 100644
index 0000000..10ae96b
--- /dev/null
+++ b/.workflows/docs.py
@@ -0,0 +1,52 @@
+"""The script generates 'docs/commands.md' file."""
+import subprocess
+
+from typing import List, Sequence
+
+
+def output(raw) -> str:
+    return raw.decode("utf-8")
+
+
+def command_output(command) -> List[str]:
+    return output(subprocess.check_output(command)).splitlines()
+
+
+def header(command: str):
+    return f"# `{command}`\n"
+
+
+def normalize_command_line(line: str):
+    if line.startswith("usage:"):
+        return f"```bash\n{line}\n```\n"
+    return f"{line}\n"
+
+
+def body() -> Sequence[str]:
+    print("Generate documentation...")
+    data = []
+    print("Explain 'git-elegant'...")
+    data.append(header("git-elegant"))
+    data.append("```bash\n")
+    data.extend(map(lambda line: f"{line}\n", command_output("bin/git-elegant")))
+    data.append("```\n\n")
+    for command in command_output(["bin/git-elegant", "show-commands"]):
+        print(f"Explain 'git-elegant {command}'...")
+        data.append(header(command))
+        data.extend(
+            map(
+                normalize_command_line,
+                command_output(["bin/git-elegant", command, "--help"]),
+            )
+        )
+    return data[:-1]
+
+
+def save_text(documentation: Sequence[str], destination: str) -> None:
+    print("Write documentation to", destination)
+    with open(destination, "w") as doc:
+        doc.writelines(documentation)
+
+
+if __name__ == "__main__":
+    save_text(body(), "docs/commands.md")
diff --git a/workflows b/workflows
index 72ee880..b8f2237 100755
--- a/workflows
+++ b/workflows
@@ -10,7 +10,7 @@ testing() {
 }
 
 generate-docs() {
-    .workflows/docs-generation.bash
+    python .workflows/docs.py
 }
 
 preview-docs() {