feat: 'mkdocs' documentation generation now works

README.md

@@ -2,6 +2,10 @@
 
 My personal store for [glue](https://github.com/eankeen/glue); visit that repository for more information about Glue
 
-TODO
+### TODO
 
-- linter for bootstrapping files and functions
+- add linter functions
+- automate social media preview, github documentation settings
+- alternative override system (auxillary configuration and local overrides to `glue.toml`)
+- `gluew`
+- "funding"?

actions/tool-dockerfilelint.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+eval "$GLUE_BOOTSTRAP"
+bootstrap
+
+action() {
+	ensure.cmd 'dockerfilelint'
+
+	if dockerfilelint ./**/Dockerfile; then
+		exitCode=$?
+	else
+		exitCode=$?
+	fi
+
+	REPLY="$exitCode"
+}
+
+action "$@"
+unbootstrap

actions/tool-hadolint.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+eval "$GLUE_BOOTSTRAP"
+bootstrap
+
+action() {
+	ensure.cmd 'hadolint'
+
+	local exitCode=0
+
+	# TODO: function run and set exit code
+	if hadolint ./**/Dockerfile; then
+		exitCode=$?
+	else
+		exitCode=$?
+	fi
+
+	REPLY="$exitCode"
+}
+
+action "$@"
+unbootstrap

actions/tool-mkdocs.sh

@@ -3,53 +3,87 @@ eval "$GLUE_BOOTSTRAP"
 bootstrap
 
 action() {
-	ensure.cmd 'toast'
+	ensure.cmd 'docker'
 
 	util.shopt -s globstar
 
 	local exitCode=0
 
 	toml.get_key 'gitRemoteUser' glue.toml
 	local gitRemoteUser="$REPLY"
+	ensure.nonZero 'gitRemoteUser' "$gitRemoteUser"
 
 	toml.get_key 'gitRemoteRepo' glue.toml
 	local gitRemoteRepo="$REPLY"
+	ensure.nonZero 'gitRemoteRepo' "$gitRemoteRepo"
 
-	bootstrap.generated 'tool-mkdocs'
-	ensure.cd "$GENERATED_DIR"
+	toml.get_key 'description' glue.toml
+	local description="$REPLY"
+	ensure.nonZero 'description' "$description"
 
-	# TODO: only import docs
-	git clone --depth 1 file://"$GLUE_WD" .
+	toml.get_key 'license' glue.toml
+	local tomlKeyLicense="$REPLY"
+	ensure.nonZero 'tomlKeyLicense' "$tomlKeyLicense"
+
+	# TODO: rename 'name' to 'author'? (or something else?)
+	toml.get_key 'name' glue.toml
+	local tomlKeyName="$REPLY"
+	ensure.nonZero 'tomlKeyName' "$tomlKeyName"
+
+	toml.get_key 'project' glue.toml
+	local tomlKeyProject="$REPLY"
+	ensure.nonZero 'tomlKeyProject' "$tomlKeyProject"
 
 	# glue useConfig(tool-mkdocs)
 	util.get_config 'tool-mkdocs/mkdocs.yml'
 	local cfgMkdocsYml="$REPLY"
 
-	util.get_config 'tool-mkdocs/pyproject.toml'
-	local cfgPyprojectToml="$REPLY"
-
-	util.get_config 'tool-mkdocs/toast.yml'
-	local cfgToastYml="$REPLY"
-
-	cp "$cfgMkdocsYml" "$cfgPyprojectToml" "$cfgToastYml" .
-
-	ensure.file "$GLUE_WD/README.md"
-	cp "$GLUE_WD/README.md" 'docs/index.md'
-
-	# Copy specialized files to 'docs' before build
-	util.run_hook 'hook.tool-mkdocs.copy_docs'
-
-	toast mkdocs
-	cp -r "$GENERATED_DIR/site" "site"
-
-	ensure.cd site
-	git init --initial-branch=main
-	git add -A
-	# TODO: commit message
-	git commit -m 'Update site'
-	# TODO: rebase or configure merge strategy
-	git push -f "https://github.com/$gitRemoteUser/$gitRemoteRepo.git" main:gh-pages
-	unbootstrap.generated
+	util.get_config 'tool-mkdocs/Dockerfile'
+	local cfgDockerfile="$REPLY"
+
+	bootstrap.generated 'tool-mkdocs'; {
+		ensure.cd "$GENERATED_DIR"
+
+		cp "$cfgMkdocsYml" "$cfgDockerfile" .
+
+		sed -i \
+			-e "s/TEMPLATE_SITE_NAME/$tomlKeyProject/g" \
+			-e "s/TEMPLATE_REMOTE_USER/$gitRemoteUser/g" \
+			-e "s/TEMPLATE_REMOTE_REPO/$gitRemoteRepo/g" \
+			-e "s/TEMPLATE_DESCRIPTION/$description/g" \
+			-e "s/TEMPLATE_AUTHOR/$tomlKeyProject/g" \
+			mkdocs.yml
+
+		sed -i \
+			-e "s/TEMPLATE_POETRY_NAME/$tomlKeyProject/g" \
+			-e "s/TEMPLATE_POETRY_DESCRIPTION/$description/g" \
+			-e "s/TEMPLATE_POETRY_AUTHOR/$tomlKeyName/g" \
+			-e "s/TEMPLATE_POETRY_LICENSE/$tomlKeyLicense/g" \
+			-e "s/TEMPLATE_DOCKER_LICENSE/$tomlKeyLicense/g" \
+			Dockerfile
+
+		# Copy current documentation
+		mkdir -p docs
+		cp "$GLUE_WD"/docs/* ./docs
+		ensure.file "$GLUE_WD/README.md"
+		cp "$GLUE_WD/README.md" 'docs/index.md'
+
+		# Copy specialized files to 'docs' before build
+		util.run_hook 'hook.tool-mkdocs.copy_docs'
+
+		ls -al
+		docker build -t 'tool-mkdocs-poetry:default' .
+		docker run -it --name 'tool-mkdocs-poetry-container' 'tool-mkdocs-poetry:default'
+		docker container cp 'tool-mkdocs-poetry-container:/home/op/site' 'site'
+		docker container rm -f 'tool-mkdocs-poetry-container'
+
+		ensure.cd site
+		git init --initial-branch=main
+		git add -A
+		git commit -m 'tool-mkdocs.sh: Update site'
+		# # TODO: rebase or configure merge strategy to preserve history
+		git push -f "https://github.com/$gitRemoteUser/$gitRemoteRepo.git" main:gh-pages
+	}; unbootstrap.generated
 
 	REPLY="$exitCode"
 }

configs/tool-mkdocs/Dockerfile

@@ -1,6 +1,36 @@
 FROM archlinux
 
+# TODO
+LABEL \
+	org.opencontainers.image.authors="[email protected]" \
+	org.opencontainers.image.url="TODO" \
+	org.opencontainers.image.documentation="TODO" \
+	org.opencontainers.image.source="TODO" \
+	org.opencontainers.image.version="TODO" \
+	org.opencontainers.image.revision="TODO" \
+	org.opencontainers.image.vendor="TODO" \
+	org.opencontainers.image.licenses="TEMPLATE_DOCKER_LICENSE" \
+	org.opencontainers.image.title="Documentation with mkdocs" \
+	org.opencontainers.image.description="Uses 'mkdocs' to build documentation"
+
 RUN pacman -Sy --noconfirm python poetry git
 
-RUN poetry init --name 'packageName' --description 'Description' --author 'author' -l MIT && \
-	&& poetry add mkdocs mkdocs-material mkdocs-git-revision-date-localized-plugin mike mkdocs-mermaid2-plugin mkdocs-macros-plugin
+RUN useradd -ms /bin/bash op
+USER op
+WORKDIR /home/op
+
+RUN poetry init \
+		--name "TEMPLATE_POETRY_NAME" \
+		--description "TEMPLATE_POETRY_DESCRIPTION" \
+		--author "TEMPLATE_POETRY_AUTHOR" \
+		--license  "TEMPLATE_POETRY_LICENSE" \
+		--no-interaction \
+	&& poetry add \
+		mkdocs mkdocs-material \
+		mkdocs-git-revision-date-localized-plugin \
+		mike mkdocs-mermaid2-plugin mkdocs-macros-plugin
+
+COPY --chown=op:op docs ./docs
+COPY --chown=op:op mkdocs.yml ./
+
+CMD [ "/usr/bin/bash", "-c", "poetry run mkdocs build" ]

configs/tool-mkdocs/mkdocs.yml

@@ -1,14 +1,15 @@
-site_name: Glue
-# TODO: fix
-site_url: https://github.com/eankeen/glue
-repo_url: https://github.com/eankeen/glue
-repo_name: eankeen/glue
-site_description: Glue is the manifestation of a generalized task runner with respect to language agnosticity
-site_author: Edwin Kofler
+site_name: TEMPLATE_SITE_NAME
+site_url: https://github.com/TEMPLATE_REMOTE_USER/TEMPLATE_REMOTE_REPO
+repo_url: https://github.com/TEMPLATE_REMOTE_USER/TEMPLATE_REMOTE_REPO
+repo_name: TEMPLATE_REMOTE_USER/TEMPLATE_REMOTE_REPO
+site_description: TEMPLATE_DESCRIPTION
+site_author: TEMPLATE_AUTHOR
 copyright: © 2021
 google_analytics: null
+# TODO
 remote_branch: gh-pages
 remote_name: origin
+# TODO
 edit_uri: edit/main/docs
 theme:
   name: material
@@ -75,10 +76,10 @@ plugins:
       min_search_length: 2
       lang: ['en']
       prebuild_index: false
-  - git-revision-date-localized:
-      type: timeago
-      fallback_to_build_date: false
-      enable_creation_date: true
+#   - git-revision-date-localized:
+#       type: timeago
+#       fallback_to_build_date: false
+#       enable_creation_date: true
   - mike:
       version_selector: true
       canonical_version: null

docs/compatability.md

@@ -0,0 +1,6 @@
+# Compatibility
+
+To be compatible, your directory structure must have the correct shape
+
+- For Bash, there should be a top-level `pkg` directory
+- Readme must be called `README.md` at root

scripts/lint-ignore

@@ -19,5 +19,8 @@ cd "$GLOBAL_ORIGINAL_WD"
 ./util/ensure.sh
 if ! cd "$dir"; then
 
+./actions/util-Bash-generate-bins.sh
+esac; done; ${eg:+shopt -u $eg}
+
 
 

scripts/lint.sh

@@ -10,10 +10,26 @@ shopt -s extglob nullglob globstar
 # @exitcode 1 At least one lint error
 # @exitcode 2 Discontinuity within lint code integer sequence
 
+# TODO: ensure variables after util.get_config start with 'cfg'
+# TODO: ensure get_key variables have same name as key or start with 'key' or 'member' or 'property', etc.
+# TODO: ensure bootstrap.generated is always followed by a {, and same with unbootstrap.generated, but with a }
+# TODO: ensure reply with $exitCode or $REPLY, ensure exitCode is initialized
+# TODO: check that files in 'config' are actually called and used
+
 util:is_ignored_line() {
 	local lastMatchedLine="$1"
 	local file="$2"
 
+	# Ignore comments
+	if [[ ${lastMatchedLine::1} == '#' ]]; then
+		return 0
+	fi
+
+	local regex="# glue-linter-ignore"
+	if [[ $lastMatchedLine =~ $regex ]]; then
+		return 0
+	fi
+
 	# shellcheck disable=SC1007
 	local currentIgnoreFile= currentIgnoreLine=
 	local -i haveRead=0
@@ -106,7 +122,10 @@ main() {
 		if lastMatched="$(grep -P "(?<!ensure\.)cd[ \t]+" "$file")"; then
 			util:print_lint 112 "Use 'ensure.cd' instead of 'cd'"
 		fi
-		:
+
+		if lastMatched="$(grep -P "(?<!util\.)shopt[ \t]+" "$file")"; then
+			util:print_lint 116 "Use 'util.shopt' instead of 'shopt'"
+		fi
 	done
 
 	for file in ./{actions,tasks}/?*.sh; do
@@ -133,6 +152,11 @@ main() {
 		if lastMatched="$(grep "\(||\|&&\)" "$file")"; then
 			util:print_lint 110 "Do not use '||' or '&&', as they they will not work as intended with 'set -e' enabled"
 		fi
+
+		if [ ! -x "$file" ]; then
+			lastMatched=
+			util:print_lint 115 "File not marked as executable"
+		fi
 	done
 
 	for file in ./actions/?*.sh; do

tasks/Bash.docs.sh

@@ -9,15 +9,14 @@ task() {
 	local exitOne="$REPLY"
 
 	hook.tool-mkdocs.copy_docs() {
-		mkdir -p docs
+		mkdir -p docs/shdoc
 		cp -r "$GLUE_WD/.glue/generated/tool-shdoc" ./docs/shdoc
 	}
 	# glue useAction(tool-mkdocs.sh)
 	util.get_action 'tool-mkdocs.sh'
 	source "$REPLY"
 	local exitTwo="$REPLY"
 
-	# shellcheck disable=SC2269
 	REPLY="$((exitOne | exitTwo))"
 }
 

tasks/Docker.lint.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+eval "$GLUE_BOOTSTRAP"
+bootstrap
+
+task() {
+	# glue useAction(tool-hadolint.sh)
+	util.get_action 'tool-hadolint.sh'
+	source "$REPLY"
+	local exitOne="$REPLY"
+
+	# glue useAction(tool-dockerfilelint.sh)
+	util.get_action 'tool-dockerfilelint.sh'
+	source "$REPLY"
+	local exitOne="$REPLY"
+
+	REPLY="$exitOne"
+}
+
+task "$@"
+unbootstrap

util/bootstrap.sh

@@ -4,7 +4,7 @@
 # @noargs
 bootstrap() {
 	set -eEo pipefail
-	shopt -s extglob
+	shopt -s extglob # glue-linter-ignore
 
 	unset REPLY task action
 
@@ -41,12 +41,12 @@ bootstrap() {
 	# source files in 'util'
 	local dir="util"
 
-	if shopt -q nullglob; then
+	if shopt -q nullglob; then # glue-linter-ignore
 		local shoptExitStatus="$?"
 	else
 		local shoptExitStatus="$?"
 	fi
-	shopt -s nullglob
+	shopt -s nullglob # glue-linter-ignore
 
 	local -a filesToSource=()
 
@@ -86,7 +86,7 @@ bootstrap() {
 	done
 
 	if (( shoptExitStatus != 0 )); then
-		shopt -u nullglob
+		shopt -u nullglob # glue-linter-ignore
 	fi
 
 	for file in "${filesToSource[@]}"; do
@@ -167,7 +167,7 @@ unbootstrap() {
 			-u) newOptionValue="-s" ;;
 		esac
 
-		shopt "$newOptionValue" "$optionName"
+		shopt "$newOptionValue" "$optionName" # glue-linter-ignore
 	done
 
 	_util_shopt_data=