From 1ef226f8d4fe0e66fa293eefcd69f2d4f196cfcd Mon Sep 17 00:00:00 2001
From: Joshua Hamilton <hamiltonjoshuadavid@gmail.com>
Date: Wed, 30 Oct 2024 21:02:17 -0500
Subject: [PATCH] fill out README

---
 README.md | 105 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 104 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index af3efbe..607a250 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,104 @@
-# anki-sm-2
\ No newline at end of file
+# Anki SM-2
+
+## Installation
+
+You can install the anki-sm-2 python package from [PyPI](https://pypi.org/project/anki-sm-2/) using pip:
+```
+pip install anki-sm-2
+```
+
+## Quickstart
+
+Import and initialize the Anki SM-2 Scheduler
+
+```python
+from anki_sm_2 import AnkiSM2Scheduler, Card, Rating
+
+scheduler = AnkiSM2Scheduler()
+```
+
+Create a new Card object
+
+```python
+card = Card()
+```
+
+Choose a rating and review the card
+
+```python
+"""
+Rating.Again # (==0) forgot the card
+Rating.Hard # (==1) remembered the card, but with serious difficulty
+Rating.Good # (==2) remembered the card after a hesitation
+Rating.Easy # (==3) remembered the card easily
+"""
+
+rating = Rating.Good
+
+card, review_log = scheduler.review_card(card, rating)
+
+print(f"Card rated {review_log.rating} at {review_log.review_datetime}")
+# > Card rated 3 at 2024-10-31 01:36:57.080934+00:00
+```
+
+See when the card is due next
+```python
+from datetime import datetime, timezone
+
+due = card.due
+
+# how much time between when the card is due and now
+time_delta = due - datetime.now(timezone.utc)
+
+print(f"Card due: at {due}")
+print(f"Card due in {time_delta.seconds / 60} minutes")
+# > Card due: at 2024-10-31 01:46:57.080934+00:00
+# > Card due in 9.983333333333333 minutes
+```
+
+## Usage
+
+### Timezone
+
+Anki SM-2 uses UTC time only. You can still specify custom datetimes, but they must be UTC.
+
+```python
+from anki_sm_2 import AnkiSM2Scheduler, Card, Rating, ReviewLog
+from datetime import datetime, timezone
+
+scheduler = AnkiSM2Scheduler()
+
+# create a new card on Jan. 1, 2024
+card = Card(created_at=datetime(2024, 1, 1, 0, 0, 0, 0, timezone.utc)) # right
+#card = Card(created_at=datetime(2024, 1, 1, 0, 0, 0, 0)) # wrong
+
+# review the card on Jan. 2, 2024
+card, review_log = scheduler.review_card(card=card, rating=Rating.Good, review_datetime=datetime(2024, 1, 2, 0, 0, 0, 0, timezone.utc)) # right
+#card, review_log = scheduler.review_card(card=card, rating=Rating.Good, review_datetime=datetime(2024, 1, 2, 0, 0, 0, 0)) # wrong
+```
+
+### Serialization
+
+`Card` and `ReviewLog` objects are json-serializable via their `to_dict` and `from_dict` methods for easy database storage:
+```python
+# serialize before storage
+card_dict = card.to_dict()
+review_log_dict = review_log.to_dict()
+
+# deserialize from dict
+card = Card.from_dict(card_dict)
+review_log = ReviewLog.from_dict(review_log_dict)
+```
+
+## Versioning
+
+This python package is currently unstable and adheres to the following versioning scheme:
+
+- **Minor** version will increase when a backward-incompatible change is introduced.
+- **Patch** version will increase when a bug is fixed, a new feature is added or when anything else backward compatible warrants a new release.
+
+Once this package is considered stable, the **Major** version will be bumped to 1.0.0 and will follow [semver](https://semver.org/).
+
+## Contribute
+
+Checkout [CONTRIBUTING](https://github.com/joshdavham/anki-sm-2/blob/main/CONTRIBUTING.md) to help improve Anki SM-2!
\ No newline at end of file