Metadata-Version: 2.4
Name: episodix
Version: 0.5.4
Summary: Tool to automate preparing podcast episode documents with Readeck
Author-email: Christian Stankowic <info@cstan.io>
License-Expression: GPL-3.0-only
Project-URL: Homepage, https://codeberg.org/userspace-podcast/episodix
Project-URL: Documentation, https://codeberg.org/userspace-podcast/episodix#readme
Project-URL: Repository, https://codeberg.org/userspace-podcast/episodix
Project-URL: Issues, https://codeberg.org/userspace-podcast/episodix/issues
Project-URL: Changelog, https://codeberg.org/userspace-podcast/episodix/src/branch/main/CHANGELOG.md
Keywords: podcast,jinja,markdown,document,readeck,bookmark
Classifier: Development Status :: 5 - Production/Stable
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: readeck>=0.2.0
Dynamic: license-file

# episodix

![episodix workflow](workflow.png)

`episodix` assists with preparing podcast episode documents. It reads **bookmarks** from multiple users stored on [Readeck](https://readeck.org/) instances and groups links by their **labels**. Every bookmark needs to have **only one** label set.

The script can create commonly used labels and prepare a Markdown document (links and shownotes) using **Jinja2**.

## Prerequisites

Create an **API token** for your Readeck account:

| Setting | Value |
| ------- | ----- |
| Name | `uiu` |
| Roles | Bookmarks Read/Write, Profile Read |

Copy the (opinionated) [`sample.episodixrc`](sample.episodixrc) example configuration to `.episodixrc` and add URLs and API tokens for all the users that you want to include.

## Installation

### `pip`

Install locally:

```command
$ pip3 install -e .
```

Or install over PyPi:

```command
$ pip3 install episodix
```

### Manual

Install Python requirements:

```command
$ pip3 install -u -r requirements.txt
```

## Usage

**Initialize** workflow. This creates a dummy link with commonly used labels so you have to enter them manually:

```command
$ episodix init
Initialize Readeck for user Paula
Initialize Readeck for user Simone
```

**Prepare** an episode **document**. This will read all the bookmarks from all configured users and render a template:

```command
$ episodix prepare --template episode.md.j2 E123.md
Get bookmarks from user Paula
Get bookmarks from user Simone
Render and save template
```

After the document has been created, you can **remove all** the collected bookmarks:

```command
$ episodix nuke
Nuke bookmarks from user 'Paula'
Nuke bookmarks from user 'Simone'
```

You can also filter bookmarks label, e.g. if you're also using Readeck for other purposes.

One way is to define the `-i` / `--include-labels` or `-e` / `--exclude-labels` parameters. You can either use include **or** exclude filters - they can't be combined:

```command
# prepare episode with a subset of bookmarks
$ episodix -e sle -e nixos prepare -t episode.md.j2  E123.md

# only nuke specific bookmarks
$ episodix -i feedback -i kurznews nuke
```

Those filters can also be permanent stored in the `.episodixrc` configuration file. Again, you can't combine them - separate multiple labels with a comma:

```ini
exclude_labels=tpm
# include_labels=nixos,sle
```

## Templating

Episode documents are prepared using a Jinja2 template - see [`episode.md.j2`](episode.md.j2) for an example.

The variable `user_bookmarks` contains information derived from Readeck per user **as dictionary**, e.g. `user_bookmarks['Paula']`.

Every dictionary contains raw Readeck information **per label**, e.g. `user_bookmarks['Paula']['tooltipps']`.

Readeck keys include information like:

| Key | Description |
| --- | ----------- |
| `href`, `url` | URL |
| `title` | Page title |
| `description` | Longer page description |
| `site` | Short site URL |
| `type`, `document_type` | Document type (e.g. `article`) |
| `lang` | Language (e.g. `en`) |
| `word_count` | Number of words |
| `authors` | Document authors (if supplied) |
| `reading_time` | Reading time in minutes (e.g. `3`) |
| `labels` | List of attached labels |
| `created`, `updated` | Timestamp of creation and last update |

**Note**: You can see all the information when running the tool with the `--debug` / `-d` parameter.
