readme

3 files changed, 53 insertions, 48 deletions

diff --git a/README b/README
deleted file mode 100644
index fac2e80..0000000
--- a/README
+++ /dev/null
@@ -1,48 +0,0 @@
-roka: stream directory of audiobooks to podcasting apps via RSS
-
-demo (no audio): https://demo.jordan.im/roka/
-iOS podcast app: https://demo.jordan.im/roka/apple-podcasts.png
-
-installation
-------------
-
-a) copy and populate app.cfg and uwsgi.ini from examples
-
-b) install python dependencies flask and uwsgi
-
-        $ pip install --user flask uwsgi
-
-c) run roka.py with --scan to populate audiobook JSON cache (can be re-run to
-   update cache upon download of new books)
-
-        $ ./roka.py --scan
-
-d) execute uwsgi.sh to start the server
-
-        $ ./uwsgi.sh
-
-design decisions
-----------------
-
-1. directories contained within config:ROOT_PATH are marked as audiobooks if and
-   only if they contain at least one MP3 file
-
-2. audiobooks are uniquely identifiable by the collective hash of each MP3 file
-   contained in the audiobook directory
-
-     pro: if the directory structure is changed or files are moved, RSS/download
-     link integrity is maintained, preserving app-side listening progress and
-     history
-
-     con: each MP3 file is hashed, which can be slow on spinning rust w/ large
-     collections
-
-3. XML pubDate and list order is derived from MP3 track attributes; if not
-   present or duplicates exist, tracks are sorted alphanumerically
-
-   if a book's track numbers are unique but incorrect, a preference for filename
-   sort can be established by creating an 'ignore_tracknum' file in the
-   audiobook's path
-
-4. no rebuild endpoint exists; cache-affecting routines are run externally via
-   rebuild.py
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..75572fe
--- /dev/null
+++ b/README.md
@@ -0,0 +1,53 @@
+# Roka
+
+Stream directory of audiobooks to podcasting apps via RSS.
+
+A screenshot of the web interface is [available here](screenshots/web.png).
+
+## Installation
+
+1. Copy and populate app.cfg and uwsgi.ini from examples
+
+2. Install python dependencies flask and uwsgi
+
+    ```bash
+    pip install --user flask uwsgi
+    ```
+
+3. Run roka.py with --scan to populate audiobook JSON cache (can be re-run to
+   update cache upon download of new books)
+
+    ```bash
+    ./roka.py --scan
+    ```
+
+4. Execute uwsgi.sh to start the server
+
+    ```bash
+    ./uwsgi.sh
+    ```
+
+## Design decisions
+
+1. Directories contained within config:ROOT_PATH are marked as audiobooks if and
+   only if they contain at least one MP3 file
+
+2. Audiobooks are uniquely identifiable by the collective hash of each MP3 file
+   contained in the audiobook directory
+
+   * Pro: If the directory structure is changed or files are moved, RSS/download
+     link integrity is maintained, preserving app-side listening progress and
+     history
+
+   * Con: Each MP3 file is hashed, which can be slow on spinning rust w/ large
+     collections
+
+3. XML pubDate and list order is derived from MP3 track attributes; if not
+   present or duplicates exist, tracks are sorted alphanumerically
+
+   if a book's track numbers are unique but incorrect, a preference for filename
+   sort can be established by creating an 'ignore_tracknum' file in the
+   audiobook's path
+
+4. No rebuild endpoint exists; cache-affecting routines are run externally by
+   calling roka.py directly
diff --git a/screenshots/web.png b/screenshots/web.png
new file mode 100644
index 0000000..d284fba
--- /dev/null
+++ b/screenshots/web.png