Updated readme
This commit is contained in:
Collin R
133
README.md
133
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)
|
||||
* pip (should be installed automatically alongside python)
|
||||
* [Python 3](https://www.python.org/downloads/) (specifically version 3.7 or greater)
|
||||
* 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
|
||||
Github repository.
|
||||
First, download this project using `git` or by downloading a ZIP archive from
|
||||
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
|
||||
home or data directory (OS-dependent).
|
||||
* Store all config and data in a hidden `.pointsbot` directory or similar in the
|
||||
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
|
||||
points on the fly, rather than just keeping track of points? If so, should have
|
||||
a column denoting whether the post has been deleted, if that information is
|
||||
decided to be useful when determining a user's points.
|
||||
* 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 a column denoting whether the post has been deleted, if that
|
||||
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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user