46 lines
3.3 KiB
Markdown
46 lines
3.3 KiB
Markdown
# Repository Guidelines
|
|
|
|
## Project Structure and Module Organization
|
|
- python version is `python3.13`
|
|
- `generator.py` is the main CLI that builds a single `.ics` calendar file from a story JSON.
|
|
- `config.toml` holds schedule rules (start date/time, blocked weeks/dates, organizer info).
|
|
- `stories/` contains story inputs; each file includes a `meta` object and an `events` list.
|
|
- `stories/template.json` is a starter template for new stories.
|
|
- `fredagsbar_output/` stores generated `.ics` and preview `.html` files (local artifacts ignored via `.gitignore`).
|
|
- `requirements.txt` pins Python dependencies.
|
|
|
|
## Build, Test, and Development Commands
|
|
- `python -m venv .venv` and `source .venv/bin/activate` to create a local virtualenv.
|
|
- `pip install -r requirements.txt` installs dependencies.
|
|
- `python generator.py stories/object_87-B.json` generates a calendar file in `fredagsbar_output/`.
|
|
- `python generator.py stories/object_87-B.json --preview-html` also writes an HTML preview to `fredagsbar_output/`.
|
|
- Optional flags: `--config`, `--output-dir`, `--timezone`, `--duration-minutes`, `--no-color`.
|
|
- `python generator.py stories/<your_story>.json` runs the generator with another story file.
|
|
|
|
## Coding Style and Naming Conventions
|
|
- Use standard Python style: 4-space indentation, snake_case for functions and variables.
|
|
- Keep JSON keys consistent with existing stories (`meta.name`, `meta.theme_color`, `events[].title`, `events[].story`).
|
|
- For stable calendar updates, set `meta.id` and `events[].id` (or `events[].uid` to force a specific UID). Optionally set `config.toml` `uid_namespace` to change the deterministic UID namespace.
|
|
- The generator writes back `events[].uid` after a successful run and validates existing UID values for mismatches or duplicates.
|
|
- If a prior `fredagsbar_output/FULL_SERIES_<slug>.ics` exists, its UIDs are reused and injected into the story JSON.
|
|
- Name story files with descriptive, lowercase filenames using underscores or hyphens (for example: `stories/new_story.json`).
|
|
- Output filenames are derived from `meta.name` and written as `fredagsbar_output/FULL_SERIES_<slug>.ics`.
|
|
|
|
## Testing Guidelines
|
|
- Automated tests live in `tests/`. Run `python -m unittest discover`.
|
|
- Coverage includes date skipping, UID mapping, HTML injection, and preview rendering.
|
|
- When altering scheduling logic, confirm blocked weeks/dates and holiday skipping behavior from `config.toml`.
|
|
|
|
## Commit and Pull Request Guidelines
|
|
- Use short, imperative commit subjects consistent with history (for example: "update repo path").
|
|
- Do not commit generated `.ics` files; `fredagsbar_output/` is treated as a local artifact directory.
|
|
- In PRs, describe the story or scheduling changes, and mention the output filename you generated for verification.
|
|
- If you modify `config.toml`, call out changes to dates, blocked weeks, or organizer settings in the PR description.
|
|
|
|
## Configuration and Content Tips
|
|
- Stories can include HTML in `events[].story`; the generator converts HTML to plain text for descriptions and renders the HTML in previews.
|
|
- Keep `repo_url` in `config.toml` accurate, as it is embedded in the event description.
|
|
- `blocked_dates` supports both `YYYY-MM-DD` and `MM-DD` entries.
|
|
- Optional `repo_url`, `organizer_email`, and `uid_namespace` must be strings when set.
|
|
- HTML previews include a skipped-dates section when blocked dates/weeks are encountered.
|