Updated readme

README.md

@@ -4,8 +4,8 @@
 
 * [Description](#description)
 * [Installation](#installation)
+* [Configuration](#configuration)
 * [Usage](#usage)
-* [TODO](#todo)
 * [Ideas](#ideas)
 * [Questions](#questions)
 * [License](#license)
@@ -15,10 +15,8 @@
 This is a bot for Reddit that monitors solutions to questions or problems in a
 subreddit and awards points to the user responsible for the solution.
 
-This bot is based on the description in
+This bot is intended as a solution for
 [this request](https://www.reddit.com/r/RequestABot/comments/emdeim/expert_level_bot_coding/).
-While this could be used for other subreddits, this means that it is intended
-for [r/MinecraftHelp](https://www.reddit.com/r/MinecraftHelp/).
 
 The bot will award a point to a redditor when the OP of a submission includes
 "!Solved" or "!solved" somewhere in a reply to the redditor's comment on that
@@ -47,27 +45,118 @@ awarded for each submission.
 
 Requirements:
 
-* [python3](www.python.org) (specifically, version 3.7 or greater)
+* [Python 3](https://www.python.org/downloads/) (specifically version 3.7 or greater)
-    * pip (should be installed automatically alongside python)
+    * pip (should be installed automatically with Python)
 * [pipenv](https://pipenv.readthedocs.io/en/latest/)
-    * Install by running `pip install pipenv`
+    * After installying Python & pip, install by running `pip install pipenv`
+    * For other installation options,
+        [see here](https://pipenv.readthedocs.io/en/latest/install/#installing-pipenv)
 
-First, download this project using `git` or by downloading a zipfile from the
+First, download this project using `git` or by downloading a ZIP archive from
-Github repository.
+the Github repository using the green `Clone or download` button. If ZIP, be
+sure to extract the files from the archive before moving on.
 
-To install, navigate to the project root directory and run `pipenv install`.
+To install the packages necessary for running the bot, navigate to the project
+root directory and run `pipenv install`.
 To uninstall (i.e. delete the project's virtual environment and the installed
-python packages), instead run `pipenv --rm`.
+python packages), navigate to the project root directory and instead run
+`pipenv --rm`.
 
-## Usage
+## Configuration
 
-The bot can be configured by changing the values in the configuration files:
+The bot can be configured by changing the values in the configuration files in
+the project root directory:
 
 * `praw.ini`
     - Contains the account information for the bot
 * `pointsbot.ini`
     - Contains settings for bot behavior
 
+You shouldn't have to worry about it, but if you need it, the syntax for the
+config files can be found on the
+[INI file format's Wikipedia page](https://en.wikipedia.org/wiki/INI_file).
+
+If this is your first time running the bot, you will need to copy
+`praw.sample.ini` to a new file called `praw.ini`, and likewise copy
+`pointsbot.sample.ini` to a new file called `pointsbot.ini`. Any instances of
+the word "REDACTED" should be replaced with the desired values; other values
+should work as-is, but can be changed as desired.
+
+The reason for this is that these config files (especially `praw.ini`) can
+contain sensitive information, and maintaining only sample versions of these
+files helps developers to avoid accidentally uploading that sensitive
+information to a public (or even private) code repository.
+
+### praw.ini
+
+In order to make a bot, you must first have a bot account. This could be a
+personal account, but it is wise to create a dedicate account for the bot,
+especially one with the word "bot" somewhere in the name.
+
+Once you have that, you can create a Reddit app for the bot. This is needed for
+authenticating with Reddit.
+
+1. First, go to your [app preferences](https://www.reddit.com/prefs/apps).
+2. Select the "are you a developer? create an app..." button.
+3. Provide a name for the bot, which could probably be the same as the account's
+   username.
+4. Select the "script" radio button.
+5. Provide a brief description.
+6. For the "about url", you can provide a link to this Github repository:
+    https://github.com/cur33/PointsBot
+7. Since it is unused, the "redirect uri" can be set to something like:
+    http://www.example.com/unused/redirect/uri
+8. Select "create app".
+
+Now you should be redirected to a page which contains the credentials you will
+need; under the name of the bot is the unlabeled `client_id`, and below that
+with the label "secret" is the `client_secret`.
+
+If you have already done this in the past, the `client_id` and `client_secret`
+can be found by navigating to your
+[app preferences](https://www.reddit.com/prefs/apps) and selecting the "edit"
+button for the app under the "developed applications" section.
+
+Several credentials are needed for running your bot, each of which is listed in
+the `praw.ini` config file:
+
+* `client_id`: Copy from your app preferences, as specified in the previous
+    steps.
+* `client_secret`: Copy from your app preferences, as specified in the previous
+    steps.
+* `user-agent`: This field can be left as-is, thought if you'd like, you can
+    change it by following [these guidelines]().
+* `username`: The username for the bot account.
+* `password`: The password for the bot account.
+
+### pointsbot.ini
+
+For now, these settings are pretty straightforward.
+
+The `Core` section:
+
+* `subreddit_name`: The name of the subreddit to monitor
+* `praw_site_name`: This should probably be left alone; it tells the bot which
+    credentials to use when authenticating with Reddit. It's useful for
+    development and easy testing with different accounts without having to
+    modify values in the code.
+* `database_name`: This is the filepath to the SQLite database file, which ends
+    with the `.db` file extension.
+
+The `Levels` section is used to determine the available user levels and
+corresponding flair texts.
+
+* The key on the left-hand side specifies the title and flair text for the
+    level; the case is ignored, and the text is converted to title case (first
+    letter of each word capitalized, and the rest lowercase).
+* The value on the right-hand side of each line is the total number of points
+    required to reach that level.
+
+The order of these lines doesn't matter; the bot will sort them in order of
+point totals.
+
+## Usage
+
 The simplest way to run the bot is to navigate to the project root directory and
 run:
 
@@ -75,12 +164,12 @@ run:
 pipenv run python -m pointsbot
 ```
 
-## Ideas & To-Do
+## Ideas
 
 ### Config
 
-* Store all config and data in a `.pointsbot` directory or similar in the user's
+* Store all config and data in a hidden `.pointsbot` directory or similar in the
-    home or data directory (OS-dependent).
+    user's home or data directory (OS-dependent).
 * Could do something similar to packages like PRAW:
     1. Look in current working directory first.
     2. Look in OS-dependent location next.
@@ -90,13 +179,15 @@ pipenv run python -m pointsbot
     could be a little too technical (though any more technically-minded users
     might appreciate the option).
 * Consolidate `pointsbot.ini` and `praw.ini` into a single config file.
+* Write a CLI script or GUI to handle this so the config values don't have to be
+    changed manually.
 
 ### Database
 
-Should it keep track of the solved posts for future reference and calculate
+* Should it keep track of the solved posts for future reference and calculate
-points on the fly, rather than just keeping track of points? If so, should have
+    points on the fly, rather than just keeping track of points? If so, should
-a column denoting whether the post has been deleted, if that information is
+    have a column denoting whether the post has been deleted, if that
-decided to be useful when determining a user's points.
+    information is decided to be useful when determining a user's points.
 
 ### Determining when to award points
 
@@ -150,6 +241,8 @@ To ensure that a point is awarded to the correct user:
 * Should the reply comment always tag them, even if it's not their first point?
 * When a user levels up, should the reply comment also mention that they have
     been awarded a new flair?
+* Should the comment contain a notice that the post was made by a bot, similar
+    to the notice on posts by automod?
 
 ## License
 

pointsbot.sample.ini

@@ -1,9 +1,9 @@
 [Core]
 subreddit_name = REDACTED
-praw_site_name = REDACTED
+praw_site_name = bot
-database_name = REDACTED
+database_name  = pointsbot.db
 
 [Levels]
-level one name = 1
+Helper         = 5
-level two name = 5
+Trusted Helper = 15
-level three name = 10
+Super Helper   = 40

pointsbot/bot.py

@@ -20,14 +20,15 @@ def run():
     # TODO Make levels a dict instead
     # TODO Could also make a Level class or namedtuple that contains more info, e.g.
     # flair css or template id
-    levels = [(o, config.getint('Levels', o)) for o in config.options('Levels')]
-    levels.sort(key=lambda pair: pair[1])
 
-    # levels = []
+    # levels = [(o, config.getint('Levels', o)) for o in config.options('Levels')]
-    # for opt in config.options('Levels'):
-        # levels.append((opt, config.getint('Levels', opt)))
     # levels.sort(key=lambda pair: pair[1])
 
+    levels = []
+    for opt in config.options('Levels'):
+        levels.append((opt.title(), config.getint('Levels', opt)))
+    levels.sort(key=lambda pair: pair[1])
+
     # Connect to Reddit
     reddit = praw.Reddit(site_name=config['Core']['praw_site_name'])
     subreddit = reddit.subreddit(config['Core']['subreddit_name'])

praw.sample.ini

@@ -1,6 +1,6 @@
 [bot]
-client_id=REDACTED
+client_id     = REDACTED
-client_secret=REDACTED
+client_secret = REDACTED
-user_agent=PointsBot (by /u/GlipGlorp7)
+user_agent    = PointsBot (by /u/GlipGlorp7)
-username=REDACTED
+username      = REDACTED
-password=REDACTED
+password      = REDACTED