add: Using Codespaces

* Describe how to use Codespaces with the repo.

* Add a script that wraps the generation in a single command.

Signed-off-by: mr.Shu <[email protected]>

Author: mrshu

README.md

@@ -28,7 +28,7 @@ The rules are written in a human readable formatting langue called
 [AsciiDoc](https://asciidoctor.org/docs/asciidoc-writers-guide/), which should
 make them quite readable and easy to edit, so please feel free to do so!
 
-## That's way too complicated!
+## That's way too complicated
 
 We do realize it may look like that. If you do not feel comfortable with
 suggesting a change using the process above, feel free to create a new thread
@@ -40,7 +40,6 @@ that your submission contains answers to the following sections:
 - **Explain why do you think it should be in the rules**
 - **List the relevant section(s) of previous rules (if applicable)**
 
-
 We can discuss your suggestion there, and if it makes sense someone will
 certainly put it into the actual `rules.adoc` document.
 
@@ -66,8 +65,8 @@ steps:
 At the end of this process we end up with a **HTML** and a **PDF** version of
 the AsciiDoc file we started with.
 
-This repository is connected to so called [Travis CI](http://travis-ci.org/)
-which allows us to automatically build the rules whenever any change/update
+This repository is using [GitHub Actions](./github/workflows/) which allows us to
+automatically build the rules whenever any change/update
 takes place.
 
 If you'd like to try it on your own, it should not be such a big problem,
@@ -80,3 +79,31 @@ thorugh the build process in two easy steps:
 Which will make the `rules.adoc` file (in the current working directory --
 that's the `$(pwd)` part) go through the build steps above and generate files
 `rules.html` and `rules.pdf` as a result.
+
+## Use GitHub Codespaces to edit these files
+
+GitHub now has a nice service called [Codespaces](https://github.com/features/codespaces)
+which allows us to spin up a "development environment" without having to
+install various dependencies without having to leave the web browser.
+
+Here is a short tutorial on how to edit the rules in Codespaces.
+
+### Spinning up Codespaces and building the rules
+
+1. First, navigate to the top part of the repository.
+
+2. Click on **Code** and then on **Create codespace on master**
+![Create Codespace](./images/codespaces.png)
+
+3. You should now be able to navigate the `rules.adoc` and/or `superteam_rules.adoc` files and edit them as you like.
+
+4. To actually build rules as a PDF and/or HTML, you can execute the following:
+
+        ./scripts/build-rules.bash rules
+
+5. After the script has ran, you will see lines such as the following in the output:
+
+        See the HTML version at: http://localhost:12345/tmp_rules.html
+        See the PDF version at: http://localhost:12345/tmp_rules.pdf
+
+Clicking on either should bring you to a directory listing, in which you can find `tmp_rules.html` and `tmp_rules.pdf` and have them load. Note that this is now being served from the Codespaces environment (the actual URL will have the `app.github.dev` suffix).

images/codespaces.png

@@ -0,0 +1,64 @@
+#!/bin/bash
+set -euo pipefail
+
+# Colors
+RED="\033[0;31m"
+GREEN="\033[0;32m"
+YELLOW="\033[1;33m"
+BLUE="\033[0;34m"
+RESET="\033[0m"
+
+# Variables
+SERVER_PORT=12345
+
+# Functions
+function print_error {
+  echo -e "${RED}[ERROR] $1${RESET}"
+}
+
+function print_success {
+  echo -e "${GREEN}[SUCCESS] $1${RESET}"
+}
+
+function print_info {
+  echo -e "${BLUE}[INFO] $1${RESET}"
+}
+
+# Check if the first argument is provided
+if [[ $# -lt 1 ]]; then
+  print_error "No target file specified. Usage: $0 <target-file>"
+  print_info "The target file is usually 'rules' or 'superteam_rules'."
+  exit 1
+fi
+
+TARGET=$1
+
+# Check if the target file exists
+if [[ ! -f "$TARGET.adoc" ]]; then
+  print_error "Target file '$TARGET.adoc' does not exist."
+  exit 1
+fi
+
+# Check if dependencies are installed
+for cmd in docker python; do
+  if ! command -v "$cmd" &>/dev/null; then
+    print_error "Dependency '$cmd' is not installed. Please install it and try again."
+    exit 1
+  fi
+done
+
+# Run Docker containers for processing
+print_info "Converting Asciidoc to LaTeX..."
+docker run -v "$(pwd)":/documents asciidoctor/docker-asciidoctor .ci/adoc-to-tex.sh "$TARGET"
+print_success "Asciidoc conversion complete."
+
+print_info "Converting LaTeX to PDF..."
+docker run -v "$(pwd)":/documents mrshu/texlive-dblatex .ci/tex-to-pdf.sh "$TARGET"
+print_success "PDF conversion complete."
+
+# Serve the files using Python's HTTP server
+echo -e "${YELLOW}See the HTML version at: ${BLUE}http://localhost:$SERVER_PORT/tmp_$TARGET.html${RESET}"
+echo -e "${YELLOW}See the PDF version at: ${BLUE}http://localhost:$SERVER_PORT/tmp_$TARGET.pdf${RESET}"
+
+print_info "Starting HTTP server on port $SERVER_PORT..."
+python -m http.server "$SERVER_PORT"