rubric-liturgy 0.15.1

A GNOME-native worship service planning tool for United Church of Canada ministry

Rubric

A GNOME-native worship service planning tool for United Church of Canada ministry.

Rubric integrates the Revised Common Lectionary, hymn lookup for Voices United, More Voices, and Let Us Sing, Bible passage retrieval, and export options for bulletin production.

---

Features

• Simple mode (on by default) — keeps the interface focused for everyday planning. Toggle in Preferences → View → Simple mode.
• RCL integration — lectionary readings, liturgical colour, and season for any Sunday; weekday services default to the coming Sunday with a stepper
• Lectionary year tracker — persistent Year A/B/C and season indicator in the header, updated daily
• Hymn suggestions — season and Proper-specific suggestions (Propers 4–29) from VU, MV, and LUS; left-click to view on Hymnary.org, right-click to inject into the selected element
• Hymn lookup — type VU 16 or MV 120 to fetch the title from Hymnary.org; optional inline Hymnary preview via WebKit
• Bible viewer — fetch passages in WEB, KJV, ASV, or ESV (ESV requires a free API key from api.esv.org)
• HTML export — generates a clean, print-ready HTML file and opens it in the browser
• Bulletin PDF export — compiled with the bundled Typst typesetter; no LaTeX required
  • Print (booklet) — half-letter (5.5 × 8.5 in), fold for saddle-stitch
  • Digital (screen PDF) — full letter, colour hyperlinks
• Rich text editor — per-element formatting toolbar (bold, italic, headings, lists, leader notes) with a Typst toggle for raw source editing; both modes store the same Typst content
• Live PDF preview — bulletin compiles in the background as you edit
• Per-element bulletin toggle — the 📋 button marks each element shown or hidden in the bulletin independently of the leader copy
• Bulletin preferences — church name, address, service time, website, email, phone, welcome line, accessibility note, mission statement, staff/contact list, and announcements — all in Preferences → Bulletin
• Announcement expiry — each announcement carries an optional YYYY-MM-DD expiry date; expired announcements are omitted automatically
• Past Liturgies archive — browse every saved service in a read-only viewer; insert any past element's text into the current service with one click
• Element Library — searchable database of every element from every saved service
• Bulletin preview panel — live preview of the congregational bulletin as you edit; popout to a floating window
• Service Planner — scans the liturgy/ folder and lists all services grouped into Upcoming and Past
• GitHub repository sync — push/pull services to a GitHub repository with one click
• Repository-aware save paths — Save As, LaTeX export, and bulletin export default to the right subfolder when a repository is configured
• Scripture translation selector — choose WEB, KJV, ASV, or ESV in Preferences → Scripture
• Undo / Redo — Ctrl+Z and Ctrl+Shift+Z
• Snippets library — reusable liturgical texts (advanced mode)
• Responsive reading builder — L:/P: syntax for formatted call-and-response text (advanced mode)
• CSV export — for sharing with musicians and AV teams (advanced mode)

---

Requirements

• Python 3.10+
• GTK4 + libadwaita + python3-gobject (system packages)

openSUSE / Leap / Tumbleweed:

sudo zypper install python3-gobject typelib-1_0-Adw-1 typelib-1_0-Gtk-4_0

Ubuntu / Debian:

sudo apt install python3-gi python3-gi-cairo gir1.2-gtk-4.0 gir1.2-adw-1

Fedora:

sudo dnf install python3-gobject gtk4 libadwaita

PDF compilation uses the bundled Typst typesetter — no LaTeX or TeX Live required. If Typst is not bundled in your install, it also accepts a system typst binary on your PATH.

---

Installation

Debian/Ubuntu (recommended)

Download rubric-liturgy_<version>_all.deb from the latest release:

sudo apt install ./rubric-liturgy_*.deb

Installs system-wide to /usr/share/rubric/ with a launcher at /usr/bin/rubric. Registers the .desktop entry, icons, MIME type, and AppStream metainfo automatically.

openSUSE / Fedora (recommended)

Download rubric-liturgy-<version>-1.noarch.rpm from the latest release:

# openSUSE
sudo zypper install ./rubric-liturgy-*.noarch.rpm

# Fedora
sudo dnf install ./rubric-liturgy-*.noarch.rpm

pipx

pipx installs Rubric into an isolated environment and puts the rubric command on your PATH. Because Rubric uses system GTK libraries, pass --system-site-packages:

pipx install --system-site-packages rubric-liturgy

To update later: pipx upgrade rubric-liturgy

Run rubric-desktop-install once after installing to register the .desktop entry, icon, and MIME type.

pip

pip install --user rubric-liturgy

Make sure ~/.local/bin is on your PATH (echo $PATH). Add it permanently with:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Run rubric-desktop-install once after installing to register the .desktop entry, icon, and MIME type.

git clone (development / manual install)

git clone https://github.com/calstfrancis/rubric.git
cd rubric
bash install.sh

The install script copies app files to ~/.local/share/rubric/, creates a launcher at ~/.local/bin/rubric, installs the .desktop entry and icons, and registers the .liturgy MIME type.

---

Usage

rubric

Or search for Rubric in GNOME Shell or your desktop launcher.

On first launch, a welcome wizard offers three starting points: today's lectionary, a blank service, or a guided tour.

---

File format

Service files use the .liturgy extension (JSON). They store the service title, date, and ordered elements. Each element carries a content_typst field with Typst markup for both leader notes and bulletin text.

---

Running tests

python3 -m unittest test_rcl_data test_bible_api -v

---

Project structure

rubric.py              Main application
rcl_data.py            RCL lectionary database and calendar logic
hymn_lookup.py         Hymnary.org title fetcher (VU, MV, LUS)
hymn_suggestions.py    Season and Proper-specific hymn suggestions
bible_api.py           Bible passage fetcher (WEB, KJV, ASV, ESV)
snippets.py            Default liturgical text snippets
observances.py         Liturgical calendar and observances intelligence
rubric_package/        Packaged models, utils, exporters, and data
install.sh             Manual install script (git clone path)
HELP.md                User guide
FAQ.md                 Frequently asked questions
CHANGELOG.md           Version history
RELEASING.md           How to cut a release

---

Contributing

Contributions welcome — bug reports, hymn suggestion additions, and UCC-specific liturgical content especially so.

Please open an issue before starting significant work.

---

Acknowledgements

• Lectionary data from the Revised Common Lectionary
• Hymn data from Hymnary.org
• Bible text from the World English Bible (public domain), King James Version (public domain), American Standard Version (public domain), and ESV (free ministry API)
• Built with GTK4 and libadwaita

---

License

GPL-3.0 — see LICENSE

---

Developed at Atlantic School of Theology, Halifax, Nova Scotia.