feat:docs as sphinx

CLAUDE.md

@@ -67,6 +67,7 @@ components/backend/
 ├── internal/logx/logx.go         # slog setup + Fatal helper
 └── Schema.md                     # human-readable DB reference (auto-generated)
 components/frontend/              # SvelteKit; generated gRPC clients under src/lib/server/grpc/generated/
+docs/                             # user documentation: Sphinx + Markdown (MyST), one guide per role, under src/
 helm-chart/                       # Helm chart; published as an OCI artifact on a v* tag
 CHANGELOG.md                      # user-visible changes; the entry lands in the PR
 RELEASING.md                      # branch model + how a change reaches a cluster
@@ -104,6 +105,9 @@ just version::show              # declared version + what a build stamps in the
 just version::check             # fail if a component version has drifted from VERSION
 just version::bump patch|minor|major   # edit VERSION everywhere, commit, annotated tag
 
+just docs::build                # build the user docs; any Sphinx warning (e.g. a broken link) fails
+just docs::serve [port]         # live preview of the docs while writing, default :8090
+
 just helm::lint                 # helm lint + full render against tools/helm/lint-values.yaml
 just helm::template [args]      # render the chart to stdout
 just helm::check-bump           # fail if helm-chart/ changed without a version bump

docs/.component.yaml

@@ -0,0 +1,11 @@
+name: docs
+version: 0.1.0
+language: none
+
+# The user documentation: a Sphinx site written in Markdown (MyST), published to
+# GitHub Pages from main. `just docs::serve` previews it while writing.
+targets:
+  build:
+    steps:
+      - runnerID: hackagon::doc-sphinx
+    inputs: ["self"]

docs/.gitignore

@@ -0,0 +1 @@
+.venv

docs/pyproject.toml

@@ -0,0 +1,20 @@
+[project]
+name = "hackagon-docs"
+version = "0.1.0"
+description = "User documentation for the Hackagon hackathon platform"
+requires-python = ">=3.11"
+dependencies = [
+  "sphinx>=8.1",
+  # Markdown instead of reStructuredText, so the docs are formatted and
+  # written like every other .md file in the repo.
+  "myst-parser>=4.0",
+  "furo>=2024.8.6",
+]
+
+[dependency-groups]
+# `just docs::serve`: rebuilds and reloads the browser on every save.
+dev = ["sphinx-autobuild>=2024.10.3"]
+
+[tool.uv]
+# A set of pages, not an installable package.
+package = false

docs/src/conf.py

@@ -0,0 +1,28 @@
+"""Sphinx configuration for the Hackagon user documentation."""
+
+from pathlib import Path
+
+project = "Hackagon"
+author = "Swiss Data Science Center"
+copyright = "Swiss Data Science Center"
+
+# The app's one declared version (see CLAUDE.md), shown in the page footer so a
+# reader can tell which release the docs were built from.
+release = (Path(__file__).parents[2] / "VERSION").read_text().strip()
+version = release
+
+extensions = ["myst_parser"]
+source_suffix = {".md": "markdown"}
+
+myst_enable_extensions = [
+    # ::: fences for notes and warnings, which keep rendering as plain text in
+    # a Markdown preview instead of breaking it.
+    "colon_fence",
+]
+# Anchors for headings down to ###, so a page can link to a section of another
+# and the app can link straight to one.
+myst_heading_anchors = 3
+
+html_theme = "furo"
+html_title = "Hackagon documentation"
+html_show_sourcelink = False

docs/src/index.md

@@ -0,0 +1,24 @@
+# Hackagon documentation
+
+Hackagon is the Swiss Data Science Center's platform for running hackathons:
+
+This guide is targeted towards hackathon organizers to help them understand how to setup and organize hackathons.
+
+## User roles
+
+The platform distinguishes the following roles:
+
+- Participant in a hackathon
+- Owner of the Hackathon
+- Hackathon Organizer
+- Sysadmin
+- Keycloak Admin
+
+In this first version we will explain the Hackathon organizer and the hackathon owner's perspcetive.
+
+```{toctree}
+:maxdepth: 2
+:caption: Guides
+
+owner/index
+```

docs/src/owner/index.md

@@ -0,0 +1,9 @@
+# Hackathon owners
+
+This guide is supposed to help people 
+
+```{toctree}
+:maxdepth: 1
+
+settings
+```

docs/src/owner/settings.md

@@ -0,0 +1,154 @@
+# Settings
+
+Settings is the first page under **Manage Hackathon** in your hackathon's menu.
+It has three parts:
+
+- [**Where the hackathon is**](#where-the-hackathon-is): Which phase is running now.
+- [**What participants can do**](#what-participants-can-do): These are the important settings that steer the hackathon and open or close activities for the participants.
+- [**Tracks**](#tracks): A hackathon can have tracks but these are optional.
+
+Only the hackathon's owners and platform administrators can see or change this
+page. Every change takes effect immediately.
+
+:::{admonition} Important
+:class: important
+
+**Moving to the next phase does not open or close anything.** What participants
+may do is decided only by the switches under
+[What participants can do](#what-participants-can-do). And all these switches are set on this page only.
+
+:::
+
+
+## Where the hackathon is
+
+Phases are optional. A phase is a stretch of time with its own name, dates and
+description, and participants see them on the hackathon's Timeline. A hackathon
+runs perfectly well without any. With none, this box only offers to add the
+first one.
+
+Once you have phases, the box shows **Now** and **Next**. The current phase can
+come from two places:
+
+- **By dates**: you haven't declared a phase, so the current one is whichever
+  phase's dates include today.
+- **Declared**: you pressed the button to make a phase current. A declared phase
+  stays current until you change it, even after its dates have passed.
+
+The button below the boxes moves the marker:
+
+- **Start _phase_**: nothing is current yet, so this declares the first phase
+  still to come.
+- **Declare _phase_ current**: the dates say a phase is running, but you haven't
+  declared it. This declares that one.
+- **Advance to _phase_**: moves the marker from the current phase to the next.
+
+**Clear the marker** removes your declaration, and the current phase goes back
+to being worked out from the dates. Deleting the declared phase clears the
+marker too.
+
+## What participants can do
+
+Each switch is a permission held by every participant of this hackathon at the
+same time. You can't turn one on for some participants only. Waitlisted people
+are not participants yet, so they have none of these permissions.
+
+All switches are off when a hackathon is created.
+
+The switches appear in this order on the page.
+
+### Register
+
+When it is on, people can join the hackathon. On a public hackathon they go on
+the waitlist until you approve them. On a private one, a valid invitation lets
+them straight in.
+
+- **While it is off, invitation links don't work either.**
+- Nobody can join once the hackathon's end date has passed, even with this on.
+- You can approve people on the waitlist while it is off.
+
+### Propose projects
+
+When it is on, participants can propose a project for you to review. Whoever
+proposes a project becomes its owner.
+
+You can add projects yourself whether this is on or off.
+
+### Set team preferences
+
+When it is on, participants can mark the projects they would like to work on.
+Turning it off freezes the preferences as they are.
+
+### See team assignments
+
+When it is on, participants can see the teams and who is on them.
+
+**While it is off, participants can't see even their own team.** You always can,
+so you can form the teams first and reveal them by turning this on.
+
+### Submit project work
+
+When it is on, participants can hand in work for their team's project. Only
+people on a team can submit.
+
+Turning it off stops new submissions, but a team can still finalize a draft it
+has already started.
+
+### Vote
+
+When it is on, participants can vote, and they can see every team's submissions.
+While it is off, they see only their own team's.
+
+- **This opens all vote categories at once.** No category opens or closes by
+  itself.
+- In a jury category only its jury members can vote.
+- Nobody can vote for their own team's submission.
+
+### View results
+
+When it is on, participants can see the vote results. There is no separate step
+to publish results: every result becomes visible the moment this is on. You can
+always see them.
+
+## Why some switches don't seem to affect you
+
+The switches grant permissions to participants, not to owners. Being an owner
+does not make you a participant. As an owner you can review projects, see teams,
+submissions and results, and manage voting whatever the switches say.
+
+Two things are only ever done by participants: setting team preferences and
+submitting work. If you want to take part yourself as well, join your hackathon
+as a participant; to submit work you also need to be on a team.
+
+## One way to run a hackathon
+
+There is no fixed order. This is one common sequence, with the switches that are
+on at each stretch:
+
+| Stretch        | Switches on                               |
+| -------------- | ----------------------------------------- |
+| Registration   | Register, Propose projects                |
+| Team formation | Set team preferences                      |
+| Teams known    | See team assignments                      |
+| Hacking        | See team assignments, Submit project work |
+| Voting         | See team assignments, Vote                |
+| Results        | See team assignments, View results        |
+
+Leave Propose projects off if you set all the challenges yourself. Consider
+turning off Submit project work before voting starts, so the work doesn't change
+while people vote.
+
+## Tracks
+
+Tracks are an optional way to group projects, for example by theme or by the
+partner who set the challenge. Each track has a name and a description. Only
+owners can add, change or remove tracks.
+
+A project doesn't need a track, and one without a track is not missing anything.
+Removing a track leaves its projects without one.
+
+Nothing else depends on tracks: voting, teams and submissions treat every
+project the same, whatever its track.
+
+When a hackathon has no tracks, this box offers to add the first one. Once there
+is one, **Manage Tracks** appears in the menu.