Add README.md and initial (naive?) CI

DIAGNijmegen · Dec 4, 2023 · 436701a · 436701a
1 parent c6df006
commit 436701a
Show file tree

Hide file tree

Showing 2 changed files with 199 additions and 0 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -0,0 +1,68 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+  release:
+    types:
+      - published
+
+env:
+  MINIMUM_PYTHON_VERSION: '3.10'
+
+jobs:
+  precommit:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Install Python ${{ env.MINIMUM_PYTHON_VERSION }}
+        uses: actions/setup-python@v3
+        with:
+          python-version: ${{ env.MINIMUM_PYTHON_VERSION }}
+      - uses: actions/checkout@v3
+      - name: Install pre-commit
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install pre-commit virtualenv!=20.0.6
+          pre-commit install
+      - name: Run static code inspections
+        run: pre-commit run --all-files
+
+
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11"]
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v3
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install poetry tox tox-gh-actions
+      - name: Test with tox
+        run: |
+          tox
+
+  deploy:
+    if: github.event_name == 'release'
+    needs: [precommit, build]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Install Python ${{ env.MINIMUM_PYTHON_VERSION }}
+        uses: actions/setup-python@v3
+        with:
+          python-version: ${{ env.MINIMUM_PYTHON_VERSION }}
+      - uses: actions/checkout@v3
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install poetry
+      - name: Upload to pypi
+        env:
+          POETRY_PYPI_TOKEN_PYPI: ${{ secrets.POETRY_PYPI_TOKEN_PYPI }}
+        run: |
+          poetry publish --build
diff --git a/README.md b/README.md
@@ -0,0 +1,131 @@
+[![CI](https://github.com/DIAGNijmegen/rse-challenge-forge/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/DIAGNijmegen/rse-challenge-forge/actions/workflows/ci.yml/badge.svg?branch=main)
+[![PyPI](https://img.shields.io/pypi/v/challenge-forge)](https://pypi.org/project/challenge-forge/)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/challenge-forge)](https://pypi.org/project/challenge-forge/)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
+#  🛠️ challenge-forge
+
+A utility that generates distributable items that help challenge organizers set up their challenge more easily on
+[Grand-Challenge.org](https://grand-challenge.org/).
+
+## Install
+
+Install via PyPi:
+
+```shell
+pip install challenge-forge
+challenge-forge --help
+```
+
+## 🎒 Challenge packs
+
+A challenge pack consists of challenge-tailored examples for the following:
+* A script to _automate uploading_ data to an archive
+* A _submission algorithm_ that can be submitted to a challenge-phase
+* An _evaluation method_ that evaluates algorithm submissions and generates performance
+  metrics for ranking.
+
+
+### Usage
+```shell
+challenge-forge pack-context.json
+```
+Will use the context found in `pack-context.json` and generate a pack at the current working directory in
+a directory`dist/` (default).
+
+<details>
+
+<summary> Example of the content of `pack-context.json </summary>
+
+```JSON
+  {
+      "challenge": {
+          "slug": "challenge-slug",
+          "phases": [
+              {
+                  "slug": "phase-slug",
+                  "archive": {
+                      "url": "https://grand-challenge.org/archives/archive-slug/"
+                  },
+                  "inputs": [
+                      {
+                          "slug": "input-civ-slug",
+                          "relative_path": "images/input-value"
+                      },
+                      {
+                          "slug": "another-input-civ-slug",
+                          "relative_path": "images/another-input-value"
+                      }
+                  ],
+                  "outputs": [
+                      {
+                          "slug": "output-civ-slug",
+                          "relative_path": "images/output-value"
+                      }
+                  ]
+              },
+              {
+                  "slug": "another-phase-slug",
+                  "archive": {
+                      "url": "https://grand-challenge.org/archives/another-archive-slug/"
+                  },
+                  "inputs": [
+                      {
+                          "slug": "input-ci-slug",
+                          "relative_path": "images/input-value"
+                      },
+                      {
+                          "slug": "another-input-ci-slug",
+                          "relative_path": "images/another-input-value"
+                      }
+                  ],
+                  "outputs": [
+                      {
+                          "slug": "output-ci-slug",
+                          "relative_path": "images/output-value"
+                      }
+                  ]
+              }
+          ]
+      }
+  }
+```
+</details>
+
+Alternatively, you generate a pack by providing a JSON string directly:
+
+```shell
+challenge-forge --output-dir /tmp '{ "challenge": { "slug": "a-slug"...'
+```
+This will output a pack directory in the `/tmp` directory.
+
+## 🏗️ Development
+
+### Install locally
+Install locally challenge-forge locally (requires `poetry`):
+
+```shell
+git clone https://github.com/DIAGNijmegen/rse-challenge-forge.git
+cd rse-challenge-forge
+poetry install
+poetry run challenge-forge --help
+```
+
+### Pre-commit hooks
+Several linters and stylers run to check the formating during continuous integration. Ensure they are run before
+committing by installing [pre-commit](https://pre-commit.com/).
+
+
+### Running Tests
+use `tox` to run all tests across all supported python versions:
+```
+$ pip install tox
+$ tox
+```
+
+### Dependencies
+Under the hood challenge-forge uses:
+* [Click](https://palletsprojects.com/p/click/)
+  * a composable command line interface toolkit
+* [Cookiecutter](https://github.com/cookiecutter/cookiecutter)
+  * a utility that creates projects from project templates