From c976e2514896ec37af6a580f9ba00505559f86bb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sofus=20Albert=20H=C3=B8gsbro=20Rose?= Date: Thu, 10 Aug 2023 16:36:59 +0200 Subject: [PATCH] feat: mdbook Docker image. --- .dockerignore | 35 +++++++++ .gitignore | 40 ++++++++++ .pre-commit-config.yaml | 7 ++ Dockerfile | 41 ++++++++++ README.md | 15 ++++ run.py | 160 ++++++++++++++++++++++++++++++++++++++++ 6 files changed, 298 insertions(+) create mode 100644 .dockerignore create mode 100644 .gitignore create mode 100644 .pre-commit-config.yaml create mode 100644 Dockerfile create mode 100644 README.md create mode 100755 run.py diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000..8a732ea --- /dev/null +++ b/.dockerignore @@ -0,0 +1,35 @@ + +# You may want to customise this file depending on your Operating System +# and the editor that you use. +# +# We recommend that you use a Global Gitignore for files that are not related +# to the project. (https://help.github.com/articles/ignoring-files/#create-a-global-gitignore) + +# OS +# +# Ref: https://github.com/github/gitignore/blob/master/Global/macOS.gitignore +# Ref: https://github.com/github/gitignore/blob/master/Global/Windows.gitignore +# Ref: https://github.com/github/gitignore/blob/master/Global/Linux.gitignore +.DS_STORE +Thumbs.db + +# Editors +# +# Ref: https://github.com/github/gitignore/blob/master/Global +# Ref: https://github.com/github/gitignore/blob/master/Global/JetBrains.gitignore +# Ref: https://github.com/github/gitignore/blob/master/Global/VisualStudioCode.gitignore +.idea +.chrome +/*.log +.vscode/* +!.vscode/settings.json +!.vscode/tasks.json +!.vscode/launch.json +!.vscode/extensions.json + +# Python +**/__pycache__ +.venv + +# Local Developer Notes +dev diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..a122861 --- /dev/null +++ b/.gitignore @@ -0,0 +1,40 @@ + +# You may want to customise this file depending on your Operating System +# and the editor that you use. +# +# We recommend that you use a Global Gitignore for files that are not related +# to the project. (https://help.github.com/articles/ignoring-files/#create-a-global-gitignore) + +# OS +# +# Ref: https://github.com/github/gitignore/blob/master/Global/macOS.gitignore +# Ref: https://github.com/github/gitignore/blob/master/Global/Windows.gitignore +# Ref: https://github.com/github/gitignore/blob/master/Global/Linux.gitignore +.DS_STORE +Thumbs.db + +# Editors +# +# Ref: https://github.com/github/gitignore/blob/master/Global +# Ref: https://github.com/github/gitignore/blob/master/Global/JetBrains.gitignore +# Ref: https://github.com/github/gitignore/blob/master/Global/VisualStudioCode.gitignore +.idea +.chrome +/*.log +.vscode/* +!.vscode/settings.json +!.vscode/tasks.json +!.vscode/launch.json +!.vscode/extensions.json +**/neovide_backtraces.log + +# Python +__pycache__/ +*.py[cod] +*$py.class +.venv +.cache-trivy/ +.hypothesis/ + +# Local Developer Notes +dev diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000..c387069 --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,7 @@ +repos: + - repo: https://github.com/compilerla/conventional-pre-commit + rev: v2.3.0 + hooks: + - id: conventional-pre-commit + stages: [commit-msg] + args: [feat, fix, ci, chore] # list of Conventional Commits types to allow diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..6968f9c --- /dev/null +++ b/Dockerfile @@ -0,0 +1,41 @@ +#################### +# - Stage: Dependencies +#################### +FROM docker.io/rust:1.57-slim-bookworm AS base + +ENV CARGO_INSTALL_ROOT /usr/local/ +ENV CARGO_TARGET_DIR /tmp/target/ + +RUN \ + --mount=type=cache,target=/var/cache/apt \ + apt update && \ + apt install -y libssl-dev pkg-config ca-certificates build-essential make perl gcc libc6-dev + +ARG MDBOOK_VERSION="0.4.34" +RUN \ + --mount=type=cache,target=/tmp/target/ \ + cargo install mdbook --vers ${MDBOOK_VERSION} --verbose + +#ARG MDBOOK_LINKCHECK_VERSION="0.7.7" +#ARG MDBOOK_MERMAID_VERSION="0.12.6" +#ARG MDBOOK_KATEX_VERSION="0.5.6" +#ARG MDBOOK_ADMONISH="1.10.1" +#ARG MDBOOK_QUIZ="0.2.14" +#ARG MDBOOK_OPEN_GIT_REPO="0.0.4" +#RUN \ +# --mount=type=cache,target=/tmp/target/ \ +# cargo install mdbook-linkcheck --vers ${MDBOOK_LINKCHECK_VERSION} --verbose && \ +# cargo install mdbook-mermaid --vers ${MDBOOK_MERMAID_VERSION} --verbose && \ +# cargo install mdbook-katex --vers ${MDBOOK_KATEX_VERSION} --verbose && \ +# cargo install mdbook-admonish --vers ${MDBOOK_ADMONISH} --verbose && \ +# cargo install mdbook-quiz --vers ${MDBOOK_QUIZ} --verbose && \ +# cargo install mdbook-open-git-repo --vers ${MDBOOK_OPEN_GIT_REPO} --verbose + +#ARG MDBOOK_TOC_VERSION="0.14.0" +#RUN cargo install mdbook-toc --vers ${MDBOOK_TOC_VERSION} --verbose + +## TODO: +# - i18n: https://crates.io/crates/mdbook-i18n-helpers + +ENTRYPOINT [] +CMD [] diff --git a/README.md b/README.md new file mode 100644 index 0000000..736a5bc --- /dev/null +++ b/README.md @@ -0,0 +1,15 @@ +## Plugins +The following plugins for `mdbook` are in use: +- `linkcheck`: Checks if links in the book are alive. + - **crates.io**: https://crates.io/crates/mdbook-linkcheck +- `mermaid`: Adds support for MermaidJS diagrams. + - **MermaidJS Reference**: https://mermaidjs.github.io/ + - **crates.io**: https://crates.io/crates/mdbook-mermaid +- `toc`: Provides inline Table of Contents support. + - **crates.io**: https://crates.io/crates/mdbook-toc +- `katex`: Provides pre-rendered LaTeX math support. + - **crates.io**: https://crates.io/crates/mdbook-katex +- `admonish`: Provides styled notes, examples, etc. . + - **crates.io**: https://crates.io/crates/mdbook-admonish +- `quiz`: Provides interactive quizzes while reading. + - **crates.io**: https://crates.io/crates/mdbook-quiz diff --git a/run.py b/run.py new file mode 100755 index 0000000..ab6c495 --- /dev/null +++ b/run.py @@ -0,0 +1,160 @@ +#!/usr/bin/python3 +#Copyright (C) 2023 Sofus Albert Høgsbro Rose +# +#This program is free software: you can redistribute it and/or modify +#it under the terms of the GNU General Public License as published by +#the Free Software Foundation, either version 3 of the License, or +#(at your option) any later version. +# +#This program is distributed in the hope that it will be useful, +#but WITHOUT ANY WARRANTY; without even the implied warranty of +#MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +#GNU General Public License for more details. +# +#You should have received a copy of the GNU General Public License +#along with this program. If not, see . + +import sys +if not all([ + sys.version_info.major == 3, + sys.version_info.minor in [9, 10, 11, 12, 13], +]): + sys.exit(1) + +from pathlib import Path +import platform +import shutil +import subprocess + +#################### +# - Constants +#################### +IMAGE_NAME = "docker-mdbook" +IMAGE_VERSION = "0.4.34" + +RUST_IMAGE = "docker.io/rust" +RUST_TAG = "1-slim-bullseye" + +CMD_DEPENDENCIES = [ + 'podman', + 'git', + 'pre-commit' +] + +#################### +# - Help Text +#################### +def action_help() -> None: + print("""This script provides one-click development, CI, and deployment. + + Usage: + echo -e "./run.py [OPTION] [EXTRAS]" + + The following commands must be available: + podman + => The project is developed and run in podman containers. + git + => This project uses git for versioning, and collaboration. + pre-commit + => Enforces that certain checks pass at each commit. + + Options: + ./run.sh + => Equivilant to run.sh help. + + ./run.sh -h|h|help + => Shows this text. + + Options, Run Locally: + ./run.sh app + => Will run the app on port 9500, for local development. + + ./run.sh cli + => Will run a console in the dev container, with port 9500 closed. + + Options, Check: + ./run.sh check + => Will run all checks, including static analysis and tests. + + ./run.sh analyze-quality [OPTIONS] + => Will run the static code-quality analysis suite. + => OPTIONS will be passed directly to the tool (ruff). + + ./run.sh analyze-types [OPTIONS] + => Will run the static type checking suite. + => OPTIONS will be passed directly to the tool (pyright). + + ./run.sh analyze-security + => Will run the static security analysis suite. + + ./run.sh analyze-format [--overwrite] [OPTIONS] + => Will run the code formatter in read-only omde. + => '--overwrite' will cause the formater to reformat all files. + => OPTIONS will be passed directly to the tool (tan). + + ./run.sh test [OPTIONS] + => Will run the test suite locally. + => OPTIONS will be passed directly to the tool (pytest). + + Options, Build & Deploy: + ./run.sh build + => Will build, tag and upload a docker image appropriately. + + ./run.sh build-release + => Will build, tag and upload a docker image appropriate for release. + + Options, Housekeeping: + ./run.sh clean + => Will delete all data caused by this project's presence on your system. + """) + + +#################### +# - Utilities +#################### +def cmd_exists(cmd: str) -> bool: + """Checks if a command exists. Supports Linux, Mac, Windows. + """ + return shutil.which(cmd) is not None + + +#################### +# - Actions +#################### +def action_build() -> None: + subprocess.run([ + "podman", "build", + ".", + "--target", "base", + "--tag", f"{IMAGE_NAME}:{IMAGE_VERSION}", + ]) + +def action_publish() -> None: + action_build() + subprocess.run([ + "podman", "image", "push", "--all-tags", + f"git.sofus.io/so-rose/{IMAGE_NAME}", + ]) + + +#################### +# - Script +#################### +if __name__ == "__main__": + # Check Available Commands + for cmd in CMD_DEPENDENCIES: + if not cmd_exists(cmd) : + print("One or more dependencies are not installed. Please see --help.") + sys.exit(1) + + if len(sys.argv) > 1: + { + "build": action_build, + "publish": action_publish, + + "help": action_help, + "-h": action_help, + "--help": action_help, + }[sys.argv[1]]() + else: + action_help()