initial commit

1 files changed, 35 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..36f4f99
--- /dev/null
+++ b/README.md
@@ -0,0 +1,35 @@
+# README for coupons
+This project exists to make it easy to query the current sale papers for select grocery stores, including specifically Publix.
+
+## Upstream
+This project's upstream is at <https://bgstack15.ddns.net/cgit/coupons>.
+
+## Alternatives
+Visiting <https://southernsavers.com> manually, or each store's website.
+
+I previously started using selenium (see [aux/ads1.py](aux/ads1.py)) but that was not necessary.
+
+## Reason for existence
+To simplify and automate searching for items currently on sale
+
+## Using
+Basic usage is pretty simple. You need to specify a store at a minimum. When the script visits the webpage, it will cache the file to `$XDG_CACHE_DIR/coupons/` to reduce the amount of work needed during the same day.
+
+    ./coupons.py --store "publix" --search "candy"
+
+To use standard input from a fully-cached javascript response from the website, you could run this.
+
+    <~/.cache/coupons/publix_2022-09-01.json ./coupons.py --stdin --clean --search "candy" --pretty
+
+An already-cleaned json file would not need the **--clean** flag. But the cached values are the exact javascript+json payload from the server.
+
+See also `./coupons.py --help`.
+
+## Dependencies
+A chart for distros, or maybe just a simple package list.
+
+## Building or changing
+Only two stores are currently supported. The southernsavers.com website lists other stores that are probably drop-in capable. To learn the widgets.json path needed, use Developer Tools in a web browser to capture the full widgets.json path and add it to the **stores_url** dict.
+
+## References
+Developer Tools in Firefox