Cleaned up documentation

.gitignore

@@ -5,6 +5,7 @@ __pycache__/
 # Environment
 .idea
 .python-version
+.vscode
 todo.md
 notes
 

CHANGELOG.md

@@ -1,4 +1,5 @@
 ## Change Log
+
 All notable changes to this project will be documented in this file.
 
 ### [[Unreleased](https://github.com/Zeroji/semicolon/releases/latest)]
@@ -21,6 +22,7 @@ All notable changes to this project will be documented in this file.
   you will need to modify manually if you had changed it
 * Configuration files containing string IDs will have to be changed
   to numeric (integer) IDs
+* Cleaner Markdown doc files
 
 #### Removed
 
@@ -110,17 +112,20 @@ All notable changes to this project will be documented in this file.
 + Changelog file ;)
 + Added type checking on command arguments, done with type hints
 + Possibility to to regex checks on arguments
-+ Added basic support for argument documentation (you can add it without errors, but it's not used yet)
++ Added basic support for argument documentation (you can add it without errors,
+  but it's not used yet)
 + Added reaction support via `@cog.on_reaction` (more in doc)
 + `help` command, finally!
 
 #### Changed
 
-* Flags in `@cog.command` can now be either a string or a dictionary `{flag: description}` (for future documentation)
+* Flags in `@cog.command` can now be either a string or a dictionary
+  `{flag: description}` (for future documentation)
 
 #### Fixed
 
-* `Invalid argument count` when passing no arguments to a command using positional arguments
+* `Invalid argument count` when passing no arguments to a command using
+  positional arguments
 * Private message channels are now considered as servers (regarding settings)
 
 ### [[v0.1.1](https://github.com/Zeroji/semicolon/releases/tag/v0.1.1)]
@@ -144,8 +149,10 @@ All notable changes to this project will be documented in this file.
 * Switched from Python 3.5 to 3.6
 * Improved logging
 * Argument parsing system
-  * Commands needing all the message as one argument (like `;say`) must be declared with `@cog.command(fulltext=True)`
-  * Commands can be passed positional arguments if they are declared like `def function(*pos_args)`
+  * Commands needing all the message as one argument (like `;say`) must be
+    declared with `@cog.command(fulltext=True)`
+  * Commands can be passed positional arguments if they are declared like
+    `def function(*pos_args)`
   * Command arguments can have default values
   * Commands can be passed bash-like flags
 

INSTALL.md

@@ -1,6 +1,6 @@
 ## Installation
 
-#### Which version to choose
+### Which version to choose
 
 If you want to have a copy of `;;` for yourself to run on your own server,
 it's recommended you download a *stable release*, see for example the
@@ -10,7 +10,7 @@ If you'd rather have the latest update, no matter the possible bugs, and you
 like to tinker around and play with the new stuff, you'll prefer the
 [direct Github link](https://github.com/Zeroji/semicolon), aka dev version.
 
-#### Requirements
+### Requirements
 
 - Python 3.6 (a virtual environment is recommended)
 - PIP for Python
@@ -20,24 +20,25 @@ like to tinker around and play with the new stuff, you'll prefer the
 > active effort towards the support of it. Reported issues will be taken
 > care of, but with a low priority level.
 
-#### Downloading the code
+### Downloading the code
 
 To get the source code, you can either download it from Github or use
-`git` to clone it locally (this is the recommended way).  
+`git` to clone it locally (this is the recommended way).
+
 - Download the [latest stable build](https://github.com/Zeroji/semicolon/releases/latest)
-  (just click the "Download ZIP" button)  
-- Download the [latest source code](https://github.com/Zeroji/semicolon/archive/master.zip)  
-- Clone a specific version: `git clone --branch v0.1.0 https://github.com/Zeroji/semicolon.git`  
+  (just click the "Download ZIP" button)
+- Download the [latest source code](https://github.com/Zeroji/semicolon/archive/master.zip)
+- Clone a specific version: `git clone --branch v0.1.0 https://github.com/Zeroji/semicolon.git`
 - Clone the latest version: `git clone https://github.com/Zeroji/semicolon.git`
 
-#### Installation
+### Installation
 
 Start by navigating to the directory where you downloaded the source code.
 
 Install the required Python packages:
 `pip install -r requirements`
 
-#### Required files
+### Required files
 
 You'll need to create a `data` folder to store some required information.
 
@@ -60,7 +61,7 @@ Inside the `data` folder, create the following folder and files:
 - If you want `;;` to completely ignore some users, put their IDs in the
   `banned` file, separated by newlines.
 
-#### Running `;;`
+### Running `;;`
 
 Assuming you have done everything correctly, you should be able to run the
 bot by simply typing `python core.py` from the `semicolon` folder.

README.md

@@ -6,9 +6,10 @@ This is the repository for the *new* version of `;;`,
 a nice Discord bot with currently very few features.  
 [Old version here.](http://github.com/Zeroji/semicold)
 
-If you want to add features, feel free to [write a cog](https://github.com/Zeroji/semicolon/blob/master/doc/cogs.md)!
+If you want to add features, feel free to
+[write a cog](https://github.com/Zeroji/semicolon/blob/master/doc/cogs.md)!
 
-#### How to use
+### How to use
 
 Clone this repo, then run `pip install -r requirements`  
 Edit `config.yaml` if you need to, or create another config file
@@ -17,24 +18,26 @@ Edit `config.yaml` if you need to, or create another config file
 > Alternatively, you can run `./install.py` for a minimalistic setup
 
 To run the bot, type `./core.py` or `./core.py -c your_config.yaml`  
-Since [v0.1.1](https://github.com/Zeroji/semicolon/releases/tag/v0.1.1) you'll need Python 3.6.
+Since [v0.1.1](https://github.com/Zeroji/semicolon/releases/tag/v0.1.1) you'll
+need Python 3.6.
 
-#### How to use (Discord side)
+### How to use (Discord side)
 
 When the bot status gets yellow (idle), it means everything is properly loaded.  
 You can then call commands by typing `;command whatever arguments it takes`.
 If two cogs have the same command, type `;cog.command` to differentiate them.  
-Since multiple bots may use the `;` prefix, you can also mention `;;` instead of using the prefix:
-`@;; cog.command arguments`. You can also change the prefix to your liking if you have
-the `Manage Server` permission, check `@;; help prefix`.
+Since multiple bots may use the `;` prefix, you can also mention `;;` instead of
+using the prefix: `@;; cog.command arguments`. You can also change the prefix to
+your liking if you have the `Manage Server` permission, check `@;; help prefix`.
 
-#### Fancy ways to use commands
+### Fancy ways to use commands
 
-`;;` can now interpret commands inside other messages, if you use a "breaker" character.
-This character defaults to `|` and can be changed with the `breaker` command.  
+`;;` can now interpret commands inside other messages, if you use a "breaker"
+character. This character defaults to `|` and can be changed with the `breaker`
+command.  
 A quick how-to:  
 `Hello, can you say |;hi| ?` is equivalent to `;hi`  
 `Hello, can you ||;say hi | test` is equivalent to `;say hi | test`  
-Basically, this splits your messages in chunks delimited by `|` and evaluates them separately.
-If `;;` encounters `||`, it stops splitting and sends all the remaining text as one chunk: useful
-when said text contains a `|` 
+Basically, this splits your messages in chunks delimited by `|` and evaluates
+them separately. If `;;` encounters `||`, it stops splitting and sends all the
+remaining text as one chunk: useful when said text contains `|`.

TODO.md

@@ -5,28 +5,37 @@ which may or may not be implemented in future versions.
 
 ### To be implemented
 
-##### Next things to work on
+#### Next things to work on
 
-1. Additional permissions (bot owner/admin & bots)
+1. Better PEP8/Pylint correctness
+2. Additional permissions (bot owner/admin & bots)
 
 ### Might be implemented
 
-##### Miscellaneous
+#### Miscellaneous
 
 Server-specific owner-defined ranks & all  
 Fine-tuning of commands permissions, possible
 blacklist/whitelist of commands/users/roles  
 cron-like asynchronous tasks  
-webserver to receive webhooks
+webserver to receive webhooks  
+possible rST documentation  
 
-##### Commands
+#### Commands
 
 - Private only
 - Channel B/W list (per server)
 - Hidden
 
-##### Arguments
+#### Arguments
 
 Special arguments:
+
 - private (message.channel.is_private)
 - rank (server-specific author rank)
+
+#### Cogs
+
+- annotation for pip requirements
+- ability to hide from a server (func->bool)
+- per server/channel data/config files (FDs)