feat: Initial test of book.

.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

.gitignore

@@ -0,0 +1 @@
+book

.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

Dockerfile

@@ -0,0 +1,19 @@
+####################
+# - Stage: SSG
+####################
+FROM docker-mdbook:0.4.34 AS base
+COPY . /src
+
+RUN mdbook build /src --dest-dir /dist
+
+####################
+# - Stage: Serve Static Files
+####################
+FROM ghcr.io/static-web-server/static-web-server:2
+COPY --from=base /dist /app
+
+ENV SERVER_PORT 8787
+ENV SERVER_ROOT /app
+ENV SERVER_LOG_LEVEL info
+
+LABEL maintainer="s174509@dtu.dk"

README.md

@@ -0,0 +1,2 @@
+# TODO
+- [ ] `pre-commit install` as part of `run.sh`?

book.toml

@@ -0,0 +1,5 @@
+[book]
+authors = []
+language = "en"
+multilingual = false
+src = "src"

run.py

@@ -0,0 +1,210 @@
+#!/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 <https://www.gnu.org/licenses/>.
+
+import os
+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
+import contextlib
+
+####################
+# - Constants
+####################
+SCRIPT_PATH = Path(__file__).resolve().parent
+
+CMD_DEPENDENCIES = [
+	'podman',
+	'git',
+	'pre-commit'
+]
+
+IMAGE_NAME = "python-support"
+IMAGE_VERSION = ("0", "0", "1")
+
+####################
+# - 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
+####################
+@contextlib.contextmanager
+def cd_script_dir() -> None:
+	cwd_orig = Path.cwd()
+	
+	os.chdir(SCRIPT_PATH)
+	try:
+		yield
+	finally:
+		os.chdir(cwd_orig)
+
+def get_git_revision_hash() -> str:
+	return subprocess.check_output(
+		['git', 'rev-parse', 'HEAD']
+	).decode('ascii').strip()
+
+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",
+		
+		# :<commit_id> - Tag Commit ID
+		"--tag",
+		f"{IMAGE_NAME}:{get_git_revision_hash()}",
+		
+	])
+
+
+def action_run() -> None:
+	action_build()
+	subprocess.run([
+		"podman", "run",
+		"--rm", "-it",
+		"--publish", "8787:8787",
+	])
+
+
+def action_publish() -> None:
+	action_build()
+	
+	# Add Tags for M, M.m, M.m.p
+	for image_tag in [
+		f"{IMAGE_NAME}:{'.'.join(IMAGE_VERSION)}",
+		f"{IMAGE_NAME}:{'.'.join(IMAGE_VERSION[:2])}",
+		f"{IMAGE_NAME}:{IMAGE_VERSION[0]}",
+	]:
+		subprocess.run([
+			"podman", "tag",
+			f"{IMAGE_NAME}:{get_git_revision_hash()}",
+			image_tag
+		])
+	
+	# Publish Image
+	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)
+	
+	with cd_script_dir():
+		if len(sys.argv) > 1:
+			{
+				"run": action_run,
+				"dev": lambda: print("TBD"),
+				
+				"build": action_build,
+				"publish": action_publish,
+				
+				"help": action_help,
+				"-h": action_help,
+				"--help": action_help,
+			}[sys.argv[1]]()
+		else:
+			action_help()

src/SUMMARY.md

@@ -0,0 +1,3 @@
+# Summary
+
+- [Chapter 1](./chapter_1.md)

src/chapter_1.md

@@ -0,0 +1 @@
+# Chapter 1