From d95b96da8110043431353afea5dceda5e49b711c Mon Sep 17 00:00:00 2001 From: Edwin Kofler Date: Wed, 16 Jun 2021 01:50:17 -0700 Subject: [PATCH] feat: 'mkdocs' documentation generation now works --- README.md | 8 ++- actions/effect-git-tag.sh | 0 actions/effect-github-release.sh | 0 actions/tool-dockerfilelint.sh | 18 ++++++ actions/tool-hadolint.sh | 21 +++++++ actions/tool-mkdocs.sh | 94 +++++++++++++++++++++---------- actions/util-Bash-version-bump.sh | 0 configs/tool-mkdocs/Dockerfile | 34 ++++++++++- configs/tool-mkdocs/mkdocs.yml | 23 ++++---- docs/compatability.md | 6 ++ scripts/lint-ignore | 3 + scripts/lint.sh | 26 ++++++++- tasks/Bash.docs.sh | 3 +- tasks/Cpp.lint.sh | 0 tasks/Docker.lint.sh | 20 +++++++ util/bootstrap.sh | 10 ++-- util/toml.sh | 2 - util/util.sh | 2 +- 18 files changed, 214 insertions(+), 56 deletions(-) mode change 100644 => 100755 actions/effect-git-tag.sh mode change 100644 => 100755 actions/effect-github-release.sh create mode 100644 actions/tool-dockerfilelint.sh create mode 100644 actions/tool-hadolint.sh mode change 100644 => 100755 actions/tool-mkdocs.sh mode change 100644 => 100755 actions/util-Bash-version-bump.sh create mode 100644 docs/compatability.md mode change 100644 => 100755 tasks/Cpp.lint.sh create mode 100644 tasks/Docker.lint.sh diff --git a/README.md b/README.md index fc096c7..9891d15 100644 --- a/README.md +++ b/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"? diff --git a/actions/effect-git-tag.sh b/actions/effect-git-tag.sh old mode 100644 new mode 100755 diff --git a/actions/effect-github-release.sh b/actions/effect-github-release.sh old mode 100644 new mode 100755 diff --git a/actions/tool-dockerfilelint.sh b/actions/tool-dockerfilelint.sh new file mode 100644 index 0000000..9080800 --- /dev/null +++ b/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 diff --git a/actions/tool-hadolint.sh b/actions/tool-hadolint.sh new file mode 100644 index 0000000..c7aaa1d --- /dev/null +++ b/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 diff --git a/actions/tool-mkdocs.sh b/actions/tool-mkdocs.sh old mode 100644 new mode 100755 index 219fe8f..f9d9a27 --- a/actions/tool-mkdocs.sh +++ b/actions/tool-mkdocs.sh @@ -3,7 +3,7 @@ eval "$GLUE_BOOTSTRAP" bootstrap action() { - ensure.cmd 'toast' + ensure.cmd 'docker' util.shopt -s globstar @@ -11,45 +11,79 @@ action() { 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" } diff --git a/actions/util-Bash-version-bump.sh b/actions/util-Bash-version-bump.sh old mode 100644 new mode 100755 diff --git a/configs/tool-mkdocs/Dockerfile b/configs/tool-mkdocs/Dockerfile index 2600789..1d8565e 100644 --- a/configs/tool-mkdocs/Dockerfile +++ b/configs/tool-mkdocs/Dockerfile @@ -1,6 +1,36 @@ FROM archlinux +# TODO +LABEL \ + org.opencontainers.image.authors="edwin@kofler.dev" \ + 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" ] diff --git a/configs/tool-mkdocs/mkdocs.yml b/configs/tool-mkdocs/mkdocs.yml index 40166bf..cd05ee9 100644 --- a/configs/tool-mkdocs/mkdocs.yml +++ b/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 diff --git a/docs/compatability.md b/docs/compatability.md new file mode 100644 index 0000000..7d14ea7 --- /dev/null +++ b/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 diff --git a/scripts/lint-ignore b/scripts/lint-ignore index 0649459..41b2943 100644 --- a/scripts/lint-ignore +++ b/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} + diff --git a/scripts/lint.sh b/scripts/lint.sh index 491d535..4bf7f76 100755 --- a/scripts/lint.sh +++ b/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 "(?