diff --git a/README.md b/README.md
index ef02fb8..9be2162 100644
--- a/README.md
+++ b/README.md
@@ -1,12 +1,50 @@
+
+
## Description
+A repository to host code and a bunch of other stuff.
+Various utilities in script form for interfacing and working with ESATAN-TMS.
+
+- [Description](#description)
+- [CSV Parse/Plot](#csv-parseplot)
+ - [Usage](#usage)
+ - [End User](#end-user)
+ - [Developer](#developer)
+ - [File Structure](#file-structure)
+ - [CI](#ci)
+
+## CSV Parse/Plot
+
+### Usage
+
+#### End User
+
+Grab the binary from the [releases](https://github.com/xlxs4/loc-spotting-utils/releases) page.
+Make sure that the `.zip` you selected is appropriate for your platform, e.g., `windows.zip`.
+Extract the archive, **navigate to the `main` directory**, and start the `main` executable.
+
+#### Developer
+
+Grab the repository, and make sure you have python and [poetry](https://python-poetry.org/docs/) installed.
+- `poetry lock`
+- `poetry install --no-root -E build -E format` (`build` installs the dependencies needed for building the bundle, `format` installs the dependencies needed for `yapf`)
+- make sure to activate the poetry environment, by sourcing the appropriate `activate` script, e.g. `activate.ps1` for Powershell, located in `.venv/Scripts/`
+- for an example on how to build and format, take a look at `.github/workflows/ci.yml`
+
+
+Beginner-friendly details
+
To run the script you're going to need:
- The [Python](https://www.python.org/) programming language
- [Poetry](https://python-poetry.org/docs/#installation) (optional)
-To generate a plot (or plots) for your CSV, [clone](https://docs.gitlab.com/ee/gitlab-basics/start-using-git.html#clone-a-repository) this repository, copy or paste the CSV in the repository (`utilities` folder), then:
-
- Navigate to the `utilites` folder
- If you want to use `poetry` (recommended), do:
- If it's the first time you're doing this, run `poetry install` in your terminal
@@ -14,5 +52,122 @@ To generate a plot (or plots) for your CSV, [clone](https://docs.gitlab.com/ee/g
- If you *don't* want to use `poetry`, do:
- If it's the first time you're doing this, run `source env/bin/activate` (or `.\env\Scripts\activate` if you're on Windows)
- Run `python3 -m pip install -r requirements.txt` (it might be `py -m pip install -r requirements.txt` instead if you're on Windows)
-- Edit `src/config.toml` and add the filename of your CSV there
-- Execute the script by running `python3 src/main.py` (it might be `py src/main.py` if you're on Windows) in your terminal
\ No newline at end of file
+- Execute the script by running `python3 src/main.py` (it might be `py src/main.py` if you're on Windows) in your terminal
+
+
+
+### File Structure
+
+
+Click to expand
+
+```graphql
+./.github/workflows
+โโ ci.yml
+.gitlab-ci.yml
+./src/
+โโ config_model.py
+โโ config.toml
+โโ eltypes.py
+โโ GCodeUtils.py
+โโ GUI.py
+โโ IOUtils.py
+โโ main.py
+โโ parse.py
+โโ paths.py
+โโ plot.py
+.editorconfig
+add-files-to-spec
+example.csv
+poetry.lock
+poetry.toml
+pyproject.toml
+requirements.txt
+```
+
+### CI
+
+All [CI magic](https://github.com/AcubeSAT/esatan-utilities/actions/workflows/ci.yml) happens using [GitHub Actions](https://docs.github.com/en/actions).
+The related configuration is all located within `.github/workflows/ci.yml`:
+
+
+Click to expand
+
+```yaml
+name: CI
+run-name: ${{ github.actor }} is running ๐
+on: [push]
+
+jobs:
+ ci:
+ strategy:
+ fail-fast: false # Don't fail all jobs if a single job fails.
+ matrix:
+ python-version: ["3.11"]
+ poetry-version: ["1.2.2"] # Poetry is used for project/dependency management.
+ os: [ubuntu-latest, macos-latest, windows-latest]
+ include: # Where pip stores its cache is OS-dependent.
+ - pip-cache-path: ~/.cache
+ os: ubuntu-latest
+ - pip-cache-path: ~/.cache
+ os: macos-latest
+ - pip-cache-path: ~\appdata\local\pip\cache
+ os: windows-latest
+ defaults:
+ run:
+ shell: bash # For sane consistent scripting throughout.
+ runs-on: ${{ matrix.os }}
+ steps:
+ - name: Check out repository
+ uses: actions/checkout@v3
+ - name: Setup Python
+ id: setup-python
+ uses: actions/setup-python@v4
+ with:
+ python-version: ${{ matrix.python-version }}
+ - name: Install Poetry
+ uses: snok/install-poetry@v1
+ with:
+ version: ${{ matrix.poetry-version }}
+ virtualenvs-create: true
+ virtualenvs-in-project: true # Otherwise the venv will be the same across all OSes.
+ installer-parallel: true
+ - name: Load cached venv
+ id: cached-pip-wheels
+ uses: actions/cache@v3
+ with:
+ path: ${{ matrix.pip-cache-path }}
+ key: venv-${{ runner.os }}-${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('**/poetry.lock') }}
+ - name: Install dependencies
+ run: poetry install --no-interaction --no-root -E build -E format # https://github.com/python-poetry/poetry/issues/1227
+ - name: Check formatting
+ run: |
+ source $VENV
+ yapf -drp --no-local-style --style "facebook" src/
+ - name: Build for ${{ matrix.os }}
+ run: | # https://stackoverflow.com/questions/19456518/error-when-using-sed-with-find-command-on-os-x-invalid-command-code
+ source $VENV
+ pyi-makespec src/main.py
+ if [ "$RUNNER_OS" == "macOS" ]; then
+ sed -i '' -e '2 r add-files-to-spec' main.spec
+ sed -i '' -e 's/datas=\[]/datas=added_files/' main.spec
+ else
+ sed -i '2 r add-files-to-spec' main.spec
+ sed -i 's/datas=\[]/datas=added_files/' main.spec
+ fi
+ pyinstaller main.spec
+ - name: Archive binary artifacts
+ uses: actions/upload-artifact@v3
+ with:
+ name: ${{ matrix.os }}-bundle
+ path: dist
+```
+
+
+
+On each push, the application is bundled into a single folder containing an executable, for each OS.
+This happens using [`pyinstaller`](https://www.pyinstaller.org/).
+First there's a formatting check using [`yapf`](https://github.com/google/yapf).
+Then, the application is built.
+Everything is cached when possible.
+If the job terminates successfully, the bundle folder for each OS is uploaded as an artifact that the user can download, instead of having to run `pyinstaller` locally, or having to install `python` and the project dependencies locally through `poetry`.