Improve social media extraction and add documentation (#121)

* Improve socials extraction and testing

* Some documentation

Author: egeakman

README.md

@@ -1,41 +1,114 @@
-# programapi
+# 🎤 programapi
 
-This project downloads, processes, saves, and serves the static JSON files containing details of accepted speakers and submissions via an API.
+This project powers the **EuroPython 2025** website and Discord bot by downloading, transforming, and serving clean, structured JSON files for sessions, speakers, and the schedule, all pulled from Pretalx.
 
-Used by the EuroPython 2024 website and the Discord bot.
+Built for transparency. Designed for reuse. Optimized for EuroPython.
 
-**What this project does step-by-step:**
+---
 
-1. Downloads the Pretalx speaker and submission data, and saves it as JSON files.
-2. Transforms the JSON files into a format that is easier to work with and OK to serve publicly. This includes removing unnecessary/private fields, and adding new fields.
-3. Serves the JSON files via an API.
+## 🚀 What This Project Does
 
-## Installation
+1. **Downloads** submission and speaker data from Pretalx.
+2. **Transforms** raw data:
+   - Removes private/irrelevant fields
+   - Normalizes formats
+   - Adds computed fields (e.g. URLs, delivery mode)
+3. **Serves** the transformed JSON files via a static API.
 
-1. Clone the repository.
-2. Install the dependency management tool: ``make deps/pre``
-3. Install the dependencies: ``make deps/install``
-4. Set up ``pre-commit``: ``make pre-commit``
+---
 
-## Configuration
+## ⚙️ Installation
 
-You can change the event in the [``config.py``](src/config.py) file. It is set to ``europython-2024`` right now.
+1. **Clone the repo**
+   ```bash
+   git clone https://github.com/EuroPython/programapi.git
+   cd programapi
+   ```
 
-## Usage
+2. **Install [uv](https://docs.astral.sh/uv/getting-started/installation/)** (fast Python package manager)
 
-- Run the whole process: ``make all``
-- Run only the download process: ``make download``
-- Run only the transformation process: ``make transform``
+3. **Create a Python 3.13 virtual environment**
+   ```bash
+   uv venv -p 3.13
+   ```
 
-**Note:** Don't forget to set ``PRETALX_TOKEN`` in your ``.env`` file at the root of the project. And please don't make too many requests to the Pretalx API, it might get angry 🤪
+4. **Install dev dependencies**
+   ```bash
+   make dev
+   ```
 
-## API
+5. **Enable pre-commit hooks**
+   ```bash
+   make pre-commit
+   ```
 
-The API is served at ``https://programapi24.europython.eu/2024``. It has two endpoints (for now):
+---
 
-- ``/speakers.json``: Returns the list of confirmed speakers.
-- ``/sessions.json``: Returns the list of confirmed sessions.
+## 🛠️ Configuration
 
-## Schema
+You can update the event year or shortname in [`src/config.py`](src/config.py).
 
-See [this page](data/examples/README.md) for the explanations of the fields in the returned JSON files.
+Also, create a `.env` file in the project root and set:
+
+```env
+PRETALX_TOKEN=your_api_token_here
+```
+
+(Yes, Pretalx has rate limits. Please be nice. 🤪)
+
+---
+
+## 📦 Usage
+
+- Run the **entire pipeline**:
+  ```bash
+  make all
+  ```
+
+- Run only the **download step**:
+  ```bash
+  make download
+  ```
+
+- Run only the **transformation step**:
+  ```bash
+  make transform
+  ```
+
+- (Optional) **Exclude components**:
+  ```bash
+  make all EXCLUDE="schedule youtube"
+  ```
+
+---
+
+## 🌐 API Endpoints
+
+Hosted at:
+
+```
+https://static.europython.eu/programme/ep2025/releases/current
+```
+
+| Endpoint            | Description                                |
+|---------------------|--------------------------------------------|
+| `/speakers.json`    | List of confirmed speakers                 |
+| `/sessions.json`    | List of confirmed sessions                 |
+| `/schedule.json`    | Finalized conference schedule *(TBA)*      |
+
+---
+
+## 📖 Schema Documentation
+
+Looking for field definitions and examples?
+Check out the 👉 [`data/examples/README.md`](data/examples/README.md) for a full schema reference with example payloads and explanations.
+
+---
+
+## 💬 Questions? Feedback?
+
+Feel free to open an issue or reach us at [[email protected]](mailto:[email protected]). We love contributors 💜
+
+---
+
+📅 Last updated for: **EuroPython 2025**