document custom formatters in readme

README.md

@@ -173,6 +173,82 @@ day in the computer's timezone. Add `Z` or an offset to specify the timezone.
 * `1h30m ago`
 * `two hours thirty minutes ago`
 
+## Custom formatters
+
+You can implement your own formatters for all subcommands that display entries
+(like `t display`, `t week` etc.). It is as easy as creating an executable file
+written in any programming language (interpreted or compiled) and placing it in
+a path listed in the config value for `formatter_search_paths`.
+
+This executable will be given as standard input a csv stream with each row
+representing a time entry with the same structure as the `csv` formatter output.
+It will also be given as a command line argument representing settings for this
+formatter stored in the config file.
+
+### Example
+
+Suppose we have this config file:
+
+```toml
+database_file = "/home/user/.config/tiempo/config.toml"
+round_in_seconds = 900
+append_notes_delimiter = " "
+formatter_search_paths = ["/home/user/.config/tiempo/formatters"]
+default_formatter = "text"
+auto_sheet = "dotfiles"
+auto_sheet_search_paths = ["/home/user/.config/tiempo/auto_sheets"]
+auto_checkout = false
+require_note = true
+week_start = "Monday"
+
+[formatters.earnings]
+hourly_rate = 300
+currency = "USD"
+```
+
+then we can create the `earnings` formatter by placing the following file in
+`/home/user/.config/tiempo/formatters/earnings`:
+
+```python
+#!/usr/bin/env python3
+import sys
+import json
+import csv
+from datetime import datetime, timezone
+from datetime import timedelta
+from math import ceil
+
+config = json.loads(sys.argv[1])
+
+reader = csv.DictReader(
+    sys.stdin,
+    fieldnames=['id', 'start', 'end', 'note', 'sheet'],
+)
+
+total = timedelta(seconds=0)
+
+for line in reader:
+    if not line['end']:
+        continue
+
+    start = datetime.strptime(line['start'], '%Y-%m-%dT%H:%M:%S.%fZ')
+    end = datetime.strptime(line['end'], '%Y-%m-%dT%H:%M:%S.%fZ')
+
+    total += end - start
+
+hours = ceil(total.total_seconds() / (3600))
+earnings = hours * config['hourly_rate']
+currency = config['currency']
+
+print(f'You have earned: {earnings} {currency}')
+```
+
+Now if you run `t display -f earnings` you will get something like:
+
+```
+You have earned: 2400 USD
+```
+
 ## Why did you write this instead of improving timetrap?
 
 * timetrap is [hard to install](https://github.com/samg/timetrap/issues/176),