update command docs and readme

README.md

@@ -6,59 +6,64 @@
 
 a Discord bot that tracks new pull requests of the [ppy/osu-wiki](https://github.com/ppy/osu-wiki) repository. it's a GitHub web hook, except not really:
 
-- it's not a GitHub web hook, it's a service you have to host
+- it's not a GitHub web hook, it's a chat bot you need to host or invite
 - it can be repurposed for another repository you don't own (as well as `ppy/osu-wiki`)
 - it's stateful (has its own local database to work around API slowness)
 - it has latency (up to 2 minutes in a worst case scenario)
 - you can talk to it using miscellaneous commands. sometimes it replies
 
-## features
+### features
 
 - notify reviewers in Discord about new relevant pull requests
 - pin a pull request in Discord and keep track of it until it's closed
 - merge statistics over a time period
 
-## commands
-
-- `.help` for general overview
-- `.help commandname` for details on `commandname`
-
 ## usage
 
-I'm considering providing it as a service, but there's a long way to go. for now, [set it up yourself](#host-your-own-installation).
+- [add the bot to your server](https://discord.com/api/oauth2/authorize?client_id=742750842737655830&permissions=11264&scope=bot)
+- set up a channel for announcements using the `.set` command:
+    ```
+    .set language ru
+    .set reviewer-role @role_mention  # optional, if you want to receive pings
+    ```
+- use `.help` for general overview
+- use `.help commandname` for details on `commandname`
 
 ## host your own installation
 
+### credentials and setup
+
+requirements:
+- `python3` and `git`
+- `tmux` if you want to run it unattended
+
 1. [create a Discord application](https://discord.com/developers/applications) and add a bot account to it.
 2. add the bot to your server using a modified version of an OAuth2 authorization link from [Bot Authorization Flow](https://discord.com/developers/docs/topics/oauth2#bot-authorization-flow).
 3. clone the repository:
     ```bash
     git clone https://github.com/TicClick/librarian
     ```
-    create a modified version of `config/config.example.yaml` and fill in whatever data you need
-4. to benefit from GitHub's extended API limits, query it using an API token (get one at [Personal access tokens](https://github.com/settings/tokens))
-
-## maintenance
-
-to update to the last stable version (make sure to stop the bot beforehand):
+    create a modified version of `config/config.example.yaml` and fill in whatever data you need. to benefit from GitHub's extended API limits, query it using an API token (get one at [Personal access tokens](https://github.com/settings/tokens))
+4. setup and run the bot:
+    ```bash
+    ./bin.sh setup
+    tmux new -d -s librarian-bot "./bin.sh run --config /path/to/config"
+    ```
 
-```bash
-git fetch && git checkout main
-git pull origin main
-git checkout $( git tag --list --sort=v:refname | tail -n 1 )
-```
+### maintenance
 
-to setup the bot, run it, and be able to leave the shell without it terminating:
+stop the bot:
 
 ```bash
-./bin.sh setup
-tmux new -d -s librarian "./bin.sh run --config /path/to/config"
+tmux kill-session -t librarian
 ```
 
-to stop it:
+update to the last stable version (make sure to stop the bot beforehand):
 
 ```bash
-tmux kill-session -t librarian
+git fetch && git checkout main
+git pull origin main
+git checkout $( git tag --list --sort=v:refname | tail -n 1 )
 ```
 
 for anything else, use `bin.sh` from the source directory:
@@ -79,4 +84,5 @@ if anything goes wrong, make extensive use of a runtime log located at `{runtime
 
 ## credits
 
-see `requirements.txt` for a list of cool packages
+- bot avatar by [@drstrange777](https://twitter.com/drstrange777)
+- see `requirements.txt` for a list of cool packages

librarian/discord/cogs/pulls.py

@@ -36,7 +36,11 @@ async def list(self, ctx: commands.Context, *args):
         list pull requests merged within a time span
 
         usage:
-        .list --from 2020-01-01 --to 2021-01-01 --language ru
+            .list --from <date> --to <date> --language <code>
+
+        examples:
+            .list --from 2021-01-01 --to 2021-01-31 --language ru
+            .list -f 2020-01 -t 2020-02 -l ru
         """
 
         try:

librarian/discord/cogs/server.py

@@ -24,8 +24,10 @@ def __init__(self):
     @helpers.is_promoted()
     async def promote_users(self, ctx: commands.Context):
         """
-        allow mentioned users to change the bot's settings.
-        can be used by the server's owner or other promoted users
+        allow users to change the bot's settings or promote others. always available to the server's owner
+
+        usage:
+            .promote @Nickname @AnotherNickname
         """
 
         helper = ctx.bot.storage.discord
@@ -43,8 +45,10 @@ async def promote_users(self, ctx: commands.Context):
     @helpers.is_promoted()
     async def demote_users(self, ctx: commands.Context):
         """
-        disallow mentioned users to change the bot's settings.
-        can be used by the server's owner or other promoted users
+        disallow users to change the bot's settings or promote others. the server's owner is always promoted
+
+        usage:
+            .demote @Nickname @AnotherNickname
         """
 
         helper = ctx.bot.storage.discord
@@ -65,8 +69,12 @@ async def show(self, ctx: commands.Context, *args):
         """
         print different things
 
-        .show promoted: users that can edit settings
-        .show settings: current settings
+        usage:
+            .show <thing type>
+
+        examples:
+            .show promoted: list users that can change settings
+            .show settings: current channel settings
         """
 
         if not args or len(args) > 1:
@@ -91,7 +99,12 @@ async def show(self, ctx: commands.Context, *args):
     async def set(self, ctx: commands.Context, *args):
         """
         change translation-related settings
-        example: .set language ru reviewer-role 12345
+
+        usage:
+            .set setting-name setting-value ...
+
+        example:
+            .set language ru reviewer-role 12345
 
         known settings:
         """
@@ -115,6 +128,9 @@ async def reset(self, ctx: commands.Context):
         """
         IMMEDIATELY reset settings and promoted users for this channel,
         effectively disabling all pings and GitHub-related subscriptions
+
+        usage:
+            .reset
         """
 
         await ctx.bot.settings.reset(ctx.message.channel.id)

librarian/discord/cogs/system.py

@@ -14,9 +14,12 @@
 class System(commands.Cog):
     @commands.command(name="status")
     @helpers.is_owner()
-    async def report_status(self, ctx: commands.Context, *args):
+    async def report_status(self, ctx: commands.Context):
         """
         system information. probably only interesting to the bot owner
+
+        usage:
+            .status
         """
 
         statuses = await asyncio.gather(*(
@@ -63,6 +66,9 @@ async def run_and_reply(self, message: discord.Message, command):
     async def show_disk_status(self, ctx: commands.Context, *args):
         """
         amount of space consumed/free on a machine that hosts Librarian
+
+        usage:
+            .disk
         """
 
         await self.run_and_reply(ctx.message, ["/bin/df", "-Ph", "/"])