Use separate docker worker for serving docs

The worker Docker image for serving docs requires
- Bash for running the `git-elegant` binary and collecting the docs
- Python for running `docs.py` and `mkdocs`

The `.workflows/docs/Dockerfile` installs these dependencies as well as
`docs-workflows.bash` script that provides the following commands:
- `generate` for generating the `docs/commands.md` file
- `build` for building a static docs site using `mkdocs`
- `preview` for running docs site

All logic of worker image creation and usage is moved to `workflows`
script. However, the docs can be served without Docker just by using
`.workflows/docs/docs-workflows.bash` script - it is not recommended
way, but, sometimes, it is useful during debugging.

.workflows/ci-pipeline.bash

@@ -12,7 +12,7 @@ fail() {
 }
 
 pipeline() {
-    .workflows/bats-pipeline.bash                     || fail "Unit tests are failed."
+    .workflows/bats-pipeline.bash || fail "Unit tests are failed."
     (
         echo "Installation...."
         git config --global user.name "Elegant Git"
@@ -24,14 +24,7 @@ pipeline() {
         git elegant unknown-command | grep "Unknown command: git elegant unknown-command"
         echo "Check installation of version's file..."
         git elegant --version || exit 1
-    )                                                 || fail "Installation test is failed."
-    mkdocs build --clean --strict                     || fail "Unable to build the documentation."
-    (
-        python .workflows/docs.py
-        git update-index --really-refresh
-        git diff-index --quiet HEAD --
-    ) || fail "The documentation is not up to date. Please run 'python .workflows/docs.py' and commit the changes"
-
+    ) || fail "Installation test is failed."
 }
 
 say-version() {

.workflows/docs/Dockerfile

@@ -0,0 +1,16 @@
+ARG pythonversion=3.8.3
+FROM python:${pythonversion}-alpine
+LABEL maintainer="Dmytro Serdiuk <[email protected]>" \
+      description="The image serves the environment for docs development of Elegant Git."
+VOLUME /elegant-git
+WORKDIR /elegant-git
+ENV EG_ENABLE_TESTING true
+EXPOSE 80
+ENTRYPOINT [ "/docs-workflows.bash" ]
+CMD ["help"]
+COPY docs/requirements.txt .
+RUN python -m pip install --upgrade pip && \
+    python -m pip install -r requirements.txt
+ARG bashversion=5.0.17
+RUN apk add --no-cache bash~=${bashversion}
+COPY .workflows/docs/docs-workflows.bash /

.workflows/docs/docs-workflows.bash

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+set -e
+
+generate() {
+    exec python .workflows/docs/docs.py
+}
+
+build() {
+    local site_directory=/tmp/elegnat-git-docs
+    if test -z "${EG_ENABLE_TESTING}"; then
+        site_directory=$(pwd)/elegnat-git-docs
+    fi
+    exec python -m mkdocs build --clean --strict --site-dir ${site_directory}
+}
+
+preview() {
+    exec python -m mkdocs serve --dev-addr 0.0.0.0:80
+}
+
+help() {
+cat <<MESSAGE
+usage: ${BASH_SOURCE[0]} <command>
+
+Available commands:
+    help            prints this message
+    generate        generates fresh commands documentation
+    build           builds the static documentation site
+    preview         previews the documentation site
+
+MESSAGE
+}
+
+${1}

README.md

@@ -84,8 +84,7 @@ it. Each command file has to provide the following BASH functions:
 ### Development environment
 The following tools are needed for successful development:
 - Docker >= 19.03.2 is used for running tests
-- Python 3.x is needed for documentation previews
-- Elegant Git automates testing process and documentation generation
+- Elegant Git is used for running the testing process and generating documentation
 
 ### Coding rules
 We enforce having a consistent implementation by following the next strict rules:
@@ -148,8 +147,8 @@ The behavior should be descriptive-style (`stops with exit code 45 if cloneable
 rather than imperative-style (`stop with exit code 45 if cloneable URL is not set`).
 
 ### Updating documentation
-In order to get the documentation preview locally, please install required dependencies with
-`pip install -r docs/requirements.txt`. After, run `./workflows serve-docs`. That's it!
+In order to get a preview of the documentation site locally, please run `./workflows serve-docs`
+and open [http://localhost](http://localhost) (happens automatically if you have `open` command).
 
 The [docs/commands.md](docs/commands.md) generates by running `./workflows generate-docs` script.
 All other files in ["docs" directory](docs/) require manual corrections.

workflows

@@ -3,25 +3,53 @@ set -e
 
 source ./libexec/plugins/text
 
-WORKER_IMAGE="beeshive/elegant-git-ci:5"
+bash_5_0_17=5.0.17
+python_3_8_3=3.8.3
+
+eg_docker_organization=beeshive
+eg_documents_repository=${eg_docker_organization}/elegant-git-docs-workflows
+eg_documents_image=${eg_documents_repository}:python${python_3_8_3}-bash${bash_5_0_17}
+WORKER_IMAGE=${eg_docker_organization}/elegant-git-ci:5
+
+# docs workflows
+prepare-docs-worker() {
+    local bashversion=${bash_5_0_17}
+    local pythonversion=${python_3_8_3}
+    docker build --tag ${eg_documents_image} \
+                 --label bashversion=${bashversion} \
+                 --label pythonversion=${pythonversion} \
+                 --build-arg bashversion=${bashversion} \
+                 --build-arg pythonversion=${pythonversion} \
+                 --file .workflows/docs/Dockerfile .
+}
 
-testing() {
-    docker run -it --rm -v $PWD:/eg ${WORKER_IMAGE} .workflows/bats-pipeline.bash "$@"
+publish-docs-worker() {
+    info-text "Select image to push:"
+    select tag in $(docker image ls --filter reference=${eg_documents_repository} --format "{{.Repository}}:{{.Tag}}"); do
+        docker push ${tag}
+        break
+    done
 }
 
 generate-docs() {
-    python .workflows/docs.py
+    docker run --interactive --rm \
+               --mount type=bind,source=$(pwd),target=/elegant-git \
+               ${eg_documents_image} generate
 }
 
 preview-docs() {
-    sleep 5 && open http://localhost:8000 &
-    python -m mkdocs serve
+    { sleep 5 && open http://localhost & } || true
+    docker run --interactive --tty --rm \
+               --publish 80:80 \
+               --mount type=bind,source=$(pwd),target=/elegant-git \
+               ${eg_documents_image} preview
 }
 
 serve-docs() {
     generate-docs
     preview-docs
 }
+# docs workflows
 
 repository() {
     info-text "Start container..."
@@ -41,8 +69,36 @@ repository() {
     docker attach repository
 }
 
+# testing workflows
+testing() {
+    docker run -it --rm -v $PWD:/eg ${WORKER_IMAGE} .workflows/bats-pipeline.bash "$@"
+}
+
+__fail() {
+    error-box $@
+    exit 1
+}
+
+test-commands-docs() {
+    (
+        generate-docs
+        git update-index --really-refresh
+        git diff-index --quiet HEAD docs
+    ) || __fail "'docs/commands.md' is not up to date. Please run './workflows generate-docs' and commit the changes."
+}
+
+test-docs-site() {
+    {
+        docker run --interactive --rm \
+                   --mount type=bind,source=$(pwd),target=/elegant-git \
+                ${eg_documents_image} build
+    } || __fail "Unable to build the documentation site."
+}
+
 ci() {
     docker run --rm -v $PWD:/eg ${WORKER_IMAGE} .workflows/ci-pipeline.bash testing
+    test-commands-docs
+    test-docs-site
 }
 
 prepare-worker() {
@@ -91,37 +147,48 @@ robot() {
         exit 1
     fi
 }
+# testing workflows
 
 usage() {
     cat <<MESSAGE
 usage: ${BASH_SOURCE[0]} [command] [arg]...
 
 Available commands:
-    help            prints this message
-    testing         runs bats tests; accepts a optional pattern for tests
-                    filtering ("${BASH_SOURCE[0]} testing work" run all tests
-                    which have the word in the test name)
-    robot           runs tests for updated "libexec/git-elegant*" or
-                    "tests/git-elegant*.bats" files
-    repository      creates a git repository and installs Elegant Git within
-    generate-docs   generates fresh commands documentation bases on the latest
-                    changes
-    preview-docs    shows current documentation
-    serve-docs      generates and shows latest documentation
-    ci              runs CI quality assessment workflow
-    prepare-worker  builds a new worker image
-    publish-worker  pushes a new worker image
+  developing documentation
+    prepare-docs-worker  builds a new '${eg_documents_image}' image
+    publish-docs-worker  pushes the '${eg_documents_image}' image
+    generate-docs        generates fresh commands documentation
+    preview-docs         runs a site with the current documentation (http://localhost)
+    serve-docs           runs 'generate-docs' and 'preview-docs'
+  testing modifications
+    prepare-worker       builds a new worker image
+    publish-worker       pushes a new worker image
+    testing              runs bats tests; accepts a optional pattern for tests
+                         filtering ("${BASH_SOURCE[0]} testing work" run all tests
+                         which have the word in the test name)
+    test-commands-docs   checks if the commands docs are up to date
+    test-docs-site       checks if the docs site can be built
+    ci                   runs CI quality assessment workflow
+    robot                runs tests for updated "libexec/git-elegant*" or
+                         "tests/git-elegant*.bats" files
+  other
+    help                 prints this message
+    repository           creates a git repository and installs Elegant Git within
 MESSAGE
 }
 
 commands=(
-    usage
-    testing
-    robot
-    repository
+    prepare-docs-worker
+    publish-docs-worker
     generate-docs
     preview-docs
     serve-docs
+    testing
+    test-commands-docs
+    test-docs-site
+    usage
+    robot
+    repository
     ci
     prepare-worker
     publish-worker