diff --git a/README.md b/README.md index fce47fe..000577f 100644 --- a/README.md +++ b/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). diff --git a/images/codespaces.png b/images/codespaces.png new file mode 100644 index 0000000..a000838 Binary files /dev/null and b/images/codespaces.png differ diff --git a/scripts/build-rules.bash b/scripts/build-rules.bash new file mode 100755 index 0000000..c786ec9 --- /dev/null +++ b/scripts/build-rules.bash @@ -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 " + 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"