move files to subdirectories

11 files changed, 264 insertions, 210 deletions

diff --git a/README.md b/README.md
index 48c6103..9d1ea3f 100644
--- a/README.md
+++ b/README.md
@@ -7,217 +7,17 @@ Requires Python 3.4 or higher.
 Usage
 -----
 
-Pass the `--help` flag to a script to see its detailed usage information.
-
-### track_status.py
-
-Track when people go online/offline.
-
-    usage: track_status.py [-h] [-t TIMEOUT] [-l LOG]
-                           [--output-format {csv,log,null}] [-o OUTPUT]
-                           UID [UID ...]
-
-For example (using made up user IDs/"screen names"),
-
-    > track_status.py john.doe jane.smith
-    [2016-06-18 01:43:34] John Doe is ONLINE.
-    [2016-06-18 01:43:34] John Doe was last seen at 2016-06-18 01:33:58+03:00 using the official iPhone app.
-    [2016-06-18 01:43:34] Jane Smith is OFFLINE.
-    [2016-06-18 01:43:34] Jane Smith was last seen at 2016-06-18 01:15:47+03:00 using the web version (or an unrecognized app).
-    [2016-06-18 01:59:09] Jane Smith went ONLINE.
-    [2016-06-18 01:59:09] Jane Smith was last seen at 2016-06-18 01:59:07+03:00 using the official Android app.
-    [2016-06-18 02:10:00] John Doe went OFFLINE.
-    [2016-06-18 02:10:00] John Doe was last seen at 2016-06-18 01:54:58+03:00 using the official iPhone app.
-    ...
-
-By default, the script produces a human-readable log.
-Use the `--log` parameter to write the log to a file.
-If you want to record when people go online/offline for [further analysis],
-specify the path to a database using the `--output` parameter.
-Be careful: if the file already exists, it will be overwritten!
-
-[further analysis]: #online_durationpy
-
-### online_duration.py
-
-View the amount of time people spent online.
-
-    usage: online_duration.py [-h] [--grouping {user,date,weekday}]
-                              [--input-format {csv,log,null}]
-                              [--output-format {csv,json,img}]
-                              input [output]
-
-This script additionally requires [matplotlib] to be installed.
-
-Analyze the database produced by [track_status.py] and calculate the total
-amount of time people spent online.
-
-For example (assuming the database in "db.csv" was generated by
-[track_status.py] before):
-
-    > online_duration.py db.csv
-    89497105,John,Smith,john.smith,0:12:31
-    3698577,Jane,Smith,jane.smith,1:34:46
-
-In the example above, "John Smith" and "Jane Smith" spent approx. 13 and 95
-minutes online respectively.
-
-The output format is CSV (comma-separated values) by default.
-You can also get a JSON document:
-
-    > online_duration.py --output-format json db.csv
-    [
-       {
-          "uid": 89497105,
-          "first_name": "John",
-          "last_name": "Smith",
-          "screen_name": "john.smith",
-          "duration": "0:12:31"
-       },
-       {
-          "uid": 3698577,
-          "first_name": "Jane",
-          "last_name": "Smith",
-          "screen_name": "jane.smith",
-          "duration": "1:34:46"
-       }
-    ]
-
-The durations are calculated on a per-user basis by default.
-You can change that by supplying either `date` (to group by dates), `weekday`
-(to group by weekdays) or `hour` (to group by day hours) as the `--grouping`
-parameter value.
-For example (assuming that both Jane and Joe spent their time online on Friday,
-June 17, 2016).
-
-```
-> online_duration.py --output-format json --grouping date db.csv
-[
-   {
-      "date": "2016-06-17",
-      "duration": "1:47:17"
-   }
-]
-```
-
-```
-> online_duration.py --output-format csv --grouping weekday db.csv
-Monday,0:00:00
-Tuesday,0:00:00
-Wednesday,0:00:00
-Thursday,0:00:00
-Friday,1:47:17
-Saturday,0:00:00
-Sunday,0:00:00
-```
-
-```
-> online_duration.py --grouping hour db.csv
-0:00:00,0:00:00
-1:00:00,0:00:00
-2:00:00,0:00:00
-3:00:00,0:00:00
-4:00:00,0:03:56
-5:00:00,0:14:14
-6:00:00,0:29:30
-7:00:00,0:31:20
-8:00:00,0:12:04
-9:00:00,0:00:00
-10:00:00,0:00:00
-11:00:00,0:23:14
-12:00:00,0:06:00
-13:00:00,0:46:19
-14:00:00,0:00:00
-15:00:00,0:00:00
-16:00:00,0:00:00
-17:00:00,0:00:00
-18:00:00,0:00:00
-19:00:00,0:00:00
-20:00:00,0:00:00
-21:00:00,0:00:00
-22:00:00,0:00:00
-23:00:00,0:00:00
-```
+The main package is located in the "vk/" directory.
 
-In my opinion, the script's most useful feature is the ability to easily create
-plots that represent the text data (like in the examples above).
-To produce a plot, pass `img` as the `--output-format` parameter value and add
-a file path to write the image to.
-
-    > online_duration.py --output-format img db.csv user.png
-
-![user.png]
-
-    > online_duration.py --output-format img --grouping date db.csv date.png
-
-![date.png]
-
-    > online_duration.py --output-format img --grouping weekday db.csv weekday.png
-
-![weekday.png]
-
-    > online_duration.py --output-format img --grouping hour db.csv hour.png
-
-![hour.png]
-
-You can limit the scope of the database by supplying a time range.
-Only online durations that are within the supplied range shall then be
-processed.
-Set the range by specifying both or one of the `--from` and `--to` parameters.
-Values must be in the `%Y-%m-%dT%H:%M:%SZ` format (a subset of ISO 8601).
-
-All dates and times are in UTC.
-
-#### Known issues
-
-* When people go online using the web version and don't visit other pages over
-time (for example, just listening to music), they appear offline.
-Hence the 0:00:00 durations you might sometimes encounter.
-This might also happen using other clients.
-
-[matplotlib]: http://matplotlib.org/
-[track_status.py]: #track_statuspy
-
-[user.png]: img/online_duration/user.png
-[date.png]: img/online_duration/date.png
-[weekday.png]: img/online_duration/weekday.png
-[hour.png]: img/online_duration/hour.png
-
-### mutual_friends.py
-
-Learn who your ex and her new boyfriend are both friends with.
-
-    usage: mutual_friends.py [-h] [--output-format {csv,json}] UID [UID ...]
-
-For example (using made up user IDs/"screen names"),
-
-    > mutual_friends.py john.doe jane.doe
-    89497105,John,Smith,john.smith
-    3698577,Jane,Smith,jane.smith
-
-In the example above, both "John Doe" and "Jane Doe" are friends with "John
-Smith" and "Jane Smith", whose user IDs are 89497105 and 3698577 respectively.
-Their "screen names" (the part after "vk.com/" of their personal page URLs) are
-"john.smith" and "jane.smith".
-
-The output format is CSV (comma-separated values) by default.
-You can also get a JSON document:
+Additionally, a few scripts are supplied in the "bin/" directory to show-case
+the package's capabilities.
+Pass the `--help` flag to a script to see its detailed usage information.
+The supplied scripts are listed below.
 
-    > mutual_friends.py --output-format json john.doe jane.doe
-    [
-       {
-          "uid": 89497105,
-          "first_name": "John",
-          "last_name": "Smith",
-          "screen_name": "john.smith"
-       },
-       {
-          "uid": 3698577,
-          "first_name": "Jane",
-          "last_name": "Smith",
-          "screen_name": "jane.smith"
-       }
-    ]
+* [mutual_friends.py]: Learn who your ex and her new boyfriend are both friends
+with.
+* [track_status.py]: Track when people go online/offline.
+* [online_duration.py]: View/visualize the amount of time people spend online.
 
 License
 -------
diff --git a/mutual_friends.py b/bin/mutual_friends.py
index 8823619..8823619 100644
--- a/mutual_friends.py
+++ b/bin/mutual_friends.py
diff --git a/online_duration.py b/bin/online_duration.py
index d2d9e34..ca6fd66 100644
--- a/online_duration.py
+++ b/bin/online_duration.py
@@ -310,7 +310,7 @@ if __name__ == '__main__':
     import argparse
 
     parser = argparse.ArgumentParser(
-        description='View the amount of time people spent online.')
+        description='View/visualize the amount of time people spend online.')
 
     def grouping(s):
         try:
diff --git a/track_status.py b/bin/track_status.py
index f18d908..f18d908 100644
--- a/track_status.py
+++ b/bin/track_status.py
diff --git a/img/online_duration/date.png b/doc/images/online_duration/date.png
index 477c530..477c530 100644
--- a/img/online_duration/date.png
+++ b/doc/images/online_duration/date.png
diff --git a/img/online_duration/hour.png b/doc/images/online_duration/hour.png
index cad26b3..cad26b3 100644
--- a/img/online_duration/hour.png
+++ b/doc/images/online_duration/hour.png
diff --git a/img/online_duration/user.png b/doc/images/online_duration/user.png
index 13a7420..13a7420 100644
--- a/img/online_duration/user.png
+++ b/doc/images/online_duration/user.png
diff --git a/img/online_duration/weekday.png b/doc/images/online_duration/weekday.png
index 5cf659e..5cf659e 100644
--- a/img/online_duration/weekday.png
+++ b/doc/images/online_duration/weekday.png
diff --git a/doc/mutual_friends.md b/doc/mutual_friends.md
new file mode 100644
index 0000000..cc9396e
--- /dev/null
+++ b/doc/mutual_friends.md
@@ -0,0 +1,51 @@
+mutual_friends.py
+=================
+
+Learn who your ex and her new boyfriend are both friends with.
+
+Usage
+-----
+
+Run from the top-level directory using `python -m`.
+For example:
+
+    > python -m bin.mutual_friends -h
+    usage: mutual_friends.py [-h] [--output-format {csv,json}] UID [UID ...]
+    ...
+
+For example (using made up user IDs/"screen names"),
+
+    > python -m bin.mutual_friends john.doe jane.doe
+    89497105,John,Smith,john.smith
+    3698577,Jane,Smith,jane.smith
+
+In the example above, both "John Doe" and "Jane Doe" are friends with "John
+Smith" and "Jane Smith", whose user IDs are 89497105 and 3698577 respectively.
+Their "screen names" (the part after "vk.com/" of their personal page URLs) are
+"john.smith" and "jane.smith".
+
+The output format is CSV (comma-separated values) by default.
+You can also get a JSON document:
+
+    > python -m bin.mutual_friends --output-format json john.doe jane.doe
+    [
+       {
+          "uid": 89497105,
+          "first_name": "John",
+          "last_name": "Smith",
+          "screen_name": "john.smith"
+       },
+       {
+          "uid": 3698577,
+          "first_name": "Jane",
+          "last_name": "Smith",
+          "screen_name": "jane.smith"
+       }
+    ]
+
+See also
+--------
+
+* [License]
+
+[License]: ../README.md#license
diff --git a/doc/online_duration.md b/doc/online_duration.md
new file mode 100644
index 0000000..22af4b1
--- /dev/null
+++ b/doc/online_duration.md
@@ -0,0 +1,161 @@
+online_duration.py
+==================
+
+View/visualize the amount of time people spend online.
+
+Usage
+-----
+
+Run from the top-level directory using `python -m`.
+For example:
+
+    > python -m bin.online_duration -h
+    usage: online_duration.py [-h] [--grouping {user,date,weekday,hour}]
+                              [--input-format {csv,log,null}]
+                              [--output-format {csv,json,img}] [--from DATE_FROM]
+                              [--to DATE_TO]
+                              input [output]
+
+This script additionally requires [matplotlib] to be installed.
+
+Analyze the database produced by [track_status.py] and calculate the total
+amount of time people spent online.
+
+For example (assuming the database in "db.csv" was generated by
+[track_status.py] before):
+
+    > python -m bin.online_duration db.csv
+    89497105,John,Smith,john.smith,0:12:31
+    3698577,Jane,Smith,jane.smith,1:34:46
+
+In the example above, "John Smith" and "Jane Smith" spent approx. 13 and 95
+minutes online respectively.
+
+The output format is CSV (comma-separated values) by default.
+You can also get a JSON document:
+
+    > python -m bin.online_duration --output-format json db.csv
+    [
+       {
+          "uid": 89497105,
+          "first_name": "John",
+          "last_name": "Smith",
+          "screen_name": "john.smith",
+          "duration": "0:12:31"
+       },
+       {
+          "uid": 3698577,
+          "first_name": "Jane",
+          "last_name": "Smith",
+          "screen_name": "jane.smith",
+          "duration": "1:34:46"
+       }
+    ]
+
+The durations are calculated on a per-user basis by default.
+You can change that by supplying either `date` (to group by dates), `weekday`
+(to group by weekdays) or `hour` (to group by day hours) as the `--grouping`
+parameter value.
+For example (assuming that both Jane and Joe spent their time online on Friday,
+June 17, 2016).
+
+```
+> python -m bin.online_duration --output-format json --grouping date db.csv
+[
+   {
+      "date": "2016-06-17",
+      "duration": "1:47:17"
+   }
+]
+```
+
+```
+> python -m bin.online_duration --output-format csv --grouping weekday db.csv
+Monday,0:00:00
+Tuesday,0:00:00
+Wednesday,0:00:00
+Thursday,0:00:00
+Friday,1:47:17
+Saturday,0:00:00
+Sunday,0:00:00
+```
+
+```
+> python -m bin.online_duration --grouping hour db.csv
+0:00:00,0:00:00
+1:00:00,0:00:00
+2:00:00,0:00:00
+3:00:00,0:00:00
+4:00:00,0:03:56
+5:00:00,0:14:14
+6:00:00,0:29:30
+7:00:00,0:31:20
+8:00:00,0:12:04
+9:00:00,0:00:00
+10:00:00,0:00:00
+11:00:00,0:23:14
+12:00:00,0:06:00
+13:00:00,0:46:19
+14:00:00,0:00:00
+15:00:00,0:00:00
+16:00:00,0:00:00
+17:00:00,0:00:00
+18:00:00,0:00:00
+19:00:00,0:00:00
+20:00:00,0:00:00
+21:00:00,0:00:00
+22:00:00,0:00:00
+23:00:00,0:00:00
+```
+
+In my opinion, the script's most useful feature is the ability to easily create
+plots that represent the text data (like in the examples above).
+To produce a plot, pass `img` as the `--output-format` parameter value and add
+a file path to write the image to.
+
+    > python -m bin.online_duration --output-format img db.csv user.png
+
+![user.png]
+
+    > python -m bin.online_duration --output-format img --grouping date db.csv date.png
+
+![date.png]
+
+    > python -m bin.online_duration --output-format img --grouping weekday db.csv weekday.png
+
+![weekday.png]
+
+    > python -m bin.online_duration --output-format img --grouping hour db.csv hour.png
+
+![hour.png]
+
+You can limit the scope of the database by supplying a time range.
+Only online durations that are within the supplied range shall then be
+processed.
+Set the range by specifying both or one of the `--from` and `--to` parameters.
+Values must be in the `%Y-%m-%dT%H:%M:%SZ` format (a subset of ISO 8601).
+
+All dates and times are in UTC.
+
+[matplotlib]: http://matplotlib.org/
+[track_status.py]: track_status.md
+
+[user.png]: images/user.png
+[date.png]: images/date.png
+[weekday.png]: images/weekday.png
+[hour.png]: images/hour.png
+
+Known issues
+------------
+
+* When people go online using the web version and don't visit other pages over
+time (for example, just listening to music), they appear offline.
+Hence the 0:00:00 durations you might sometimes encounter.
+This might also happen using other clients.
+
+See also
+--------
+
+* [License]
+
+[License]: ../README.md#license
diff --git a/doc/track_status.md b/doc/track_status.md
new file mode 100644
index 0000000..8bbb380
--- /dev/null
+++ b/doc/track_status.md
@@ -0,0 +1,42 @@
+track_status.py
+===============
+
+Track when people go online/offline.
+
+Usage
+-----
+
+Run from the top-level directory using `python -m`.
+For example:
+
+    > python -m bin.track_status -h
+    usage: track_status.py [-h] [-t TIMEOUT] [-l LOG]
+                           [--output-format {csv,log,null}] [-o OUTPUT]
+                           UID [UID ...]
+    ...
+
+For example (using made up user IDs/"screen names"),
+
+    > track_status.py john.doe jane.smith
+    [2016-06-18 01:43:34] John Doe is ONLINE.
+    [2016-06-18 01:43:34] John Doe was last seen at 2016-06-18 01:33:58+03:00 using the official iPhone app.
+    [2016-06-18 01:43:34] Jane Smith is OFFLINE.
+    [2016-06-18 01:43:34] Jane Smith was last seen at 2016-06-18 01:15:47+03:00 using the web version (or an unrecognized app).
+    [2016-06-18 01:59:09] Jane Smith went ONLINE.
+    [2016-06-18 01:59:09] Jane Smith was last seen at 2016-06-18 01:59:07+03:00 using the official Android app.
+    [2016-06-18 02:10:00] John Doe went OFFLINE.
+    [2016-06-18 02:10:00] John Doe was last seen at 2016-06-18 01:54:58+03:00 using the official iPhone app.
+    ...
+
+By default, the script produces a human-readable log.
+Use the `--log` parameter to write the log to a file.
+If you want to record when people go online/offline for [further analysis],
+specify the path to a database using the `--output` parameter.
+Be careful: if the file already exists, it will be overwritten!
+
+See also
+--------
+
+* [License]
+
+[License]: ../README.md#license