Add documentation for daily offerings

freedomofkeima · Jan 20, 2017 · 3cbe0df · 3cbe0df
1 parent 853533f
commit 3cbe0df
Show file tree

Hide file tree

Showing 2 changed files with 24 additions and 6 deletions.
diff --git a/docs/offerings.rst b/docs/offerings.rst
@@ -5,11 +5,29 @@ Daily Offerings
 How It Works
 ------------
 
+Maid-chan has a scheduler worker for handling various daily tasks. For example, Maid-chan will send out daily good morning and good night greetings upon subscription. This feature is known as "Daily Offerings".
+
+Daily offerings contain of two parts: greeting and image. Greetings are taken from `maidchan/constant.py` while offerings are taken from `offerings/stock/` directory.
+
+.. autofunction:: maidchan.offerings.get_morning_offerings_text
+
+.. autofunction:: maidchan.offerings.get_night_offerings_text
+
+Offerings text functionality has two types: normal and special with 2% of probability. For example, Maid-chan sends morning greeting more than half an hour later than usual because of overslept. Greeting text on any specific day is the same for everyone, as it is stored in scheduler's metadata.
+
+.. autofunction:: maidchan.offerings.get_offerings_image
+
+.. autofunction:: maidchan.offerings.remove_offerings_image
+
+In addition to text-based greetings, Maid-chan offers image as an addition. For all images which are stored under `offerings/stock/`, Maid-chan will pick 2 random images on daily basis for morning and night offerings. Each day, used offerings are moved to `offerings/used/` directory. If there is no image under `offerings/stock/` directory, Maid-chan will simply skip sending out images as a part of daily offerings.
+
 How to Run
 ----------
 
-Greetings
----------
+1. You can start running scheduler by executing:
+
+.. code-block:: bash
+
+   $ maidchan_scheduler
 
-Image Offerings
----------------
+2. You can subscribe & unsubscribe to Maid-chan's daily offerings via `subscribe offerings` and `unsubscribe offerings` command in the Messenger. Upon subscription, you will be asked 2 questions: your usual waking up time and your usual sleeping time.
diff --git a/maidchan/japanese.py b/maidchan/japanese.py
@@ -36,7 +36,7 @@
 
 def get_kanji(level, current_pos=1):
     """
-    get_kanji return a single record of the current_pos line position
+    get_kanji returns a single record of the current_pos line position
 
     level: 1 - 4 (N1 to N4)
     current_pos: up to number of records
@@ -58,7 +58,7 @@ def get_kanji(level, current_pos=1):
 
 def get_vocabulary(current_pos=1):
     """
-    get_vocabulary return a single record of the current_pos line position
+    get_vocabulary returns a single record of the current_pos line position
 
     current_pos: up to number of records
     """