extend README and add script

README.md

@@ -1,2 +1,42 @@
 # hugo_themes_report
 A Bash Script to Generate a Report and Rank Hugo Themes
+
+The website for the themes for the Hugo Static Site
+generator, don't tell you how popular, or how recently-updated
+the themes are. But this bash script will parse the github
+api, and generate a little report for you with the
+number of stars, theme name, and date of most recent
+commit.
+
+But you'll need to set up a cron job, because you'll
+run into the github api limit if you try to look up
+info on all 172 themes at once.
+
+## Here's how you would set up a cron on Ubuntu 16.04
+You'll need to figure out what is your PATH.
+```bash
+echo $PATH
+```
+And then you'll want to export your EDITOR, because
+the `crontab -e` command invokes whatever editor
+you have specified in your environment. i.e. for
+vim `export EDITOR=vim` or add `export EDITOR=vim`
+to `.bashrc`, (and then . your bashrc again or
+restart bash).
+
+The command to edit cron is `crontab -e`, and here's 
+what a cron that runs once an hour, at ten minutes
+after the hour looks like. The new cron won't exist until
+you save AND close the editor, just saving the file isn't enough.
+
+```conf
+#!/bin/bash
+PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
+10 * * * * /home/<your user name>/bin/rank_hugo_themes.bash
+```
+
+Makes sure you make the script executable.
+
+```bash
+chmod 755 ~/bin/rank_hugo_themes.bash
+```

rank_hugo_themes.bash

@@ -0,0 +1,40 @@
+#!/bin/bash
+# rank_hugo_themes.bash
+
+REPOS_API_URL="https://api.github.com/repos"
+
+# initialize an empty array
+HUGO_THEME_REPOS=
+
+# and now populate HUGO_THEME_REPOS list
+for hugo_theme_commit_url in \
+    "$(curl -s https://api.github.com/repos/gohugoio/hugoThemes/contents/ \
+    | grep git_url | grep -v null | grep -v gohugoio | awk '{print $2}' \
+    | sed -e 's/git\/trees/commits/g' | sed -e 's/,$//g')"
+do
+    HUGO_THEME_REPOS+=($hugo_theme_commit_url)
+done
+
+HUGO_THEME_REPOS_LIST_LENGTH="${#HUGO_THEME_REPOS[@]}"
+
+# just a few at a time because of github api limit
+
+for num in {1..4}
+do
+    # pick a random hugo theme repo
+    url=${HUGO_THEME_REPOS[$((RANDOM%$HUGO_THEME_REPOS_LIST_LENGTH))]}
+    hugo_theme_user=$(echo $url | awk -F"/" '{print $5}')
+    hugo_theme=$(echo $url | awk -F"/" '{print $6}')
+    commit_hash=$(echo $url | awk -F"/" '{print $8}' | sed -e 's/"//g')
+    stars=$(curl -s "${REPOS_API_URL}/${hugo_theme_user}/${hugo_theme}" \
+        | grep stargazers_count | awk '{print $2}' | sed -e 's/,$//g' \
+        | awk '{print $NF}')
+    last_commit_date=$(curl -s \
+        "${REPOS_API_URL}/${hugo_theme_user}/${hugo_theme}/commits/${commit_hash}" \
+        | grep date | head -1 | awk '{print $2}' | sed -e 's/"//g')
+    printf "%-8s %-20s %-20s %20s\n" "$stars" "$hugo_theme" \
+        "$hugo_theme_user" "$last_commit_date" >> ~/bin/rank_hugo_themes.log
+done
+
+# modify to taste
+sort -rn ~/bin/rank_hugo_themes.log > ~/bin/rank_hugo_themes.report