Browse Source

Create some documentation on creating a Plugin.

There is now some work on creating a Plugin, as such all of the basic
stuff about creating a Plugin is documented, along with the 'Basic API'
to create a plugin.
development
Sapein 8 months ago
parent
commit
94fea839f1
1 changed files with 78 additions and 0 deletions
  1. 78
    0
      docs/CreatingAPlugin.md

+ 78
- 0
docs/CreatingAPlugin.md View File

@@ -0,0 +1,78 @@
1
+# Plugin API Tutorial  
2
+  This document describes the Plugin API and sets forth a basic tutorial for creating Plugins from somewhat basic to more complex. A passing knowledge of Python 3 is expected.
3
+
4
+### Introduction  
5
+  The Plugin API of PotatoBot is moderately complex, however there are technically two different kinds of Plugins: Basic and Complex. The Basic Plugins are going to be touched on first, with the more complex plugins being described later. Please note that the API for Basic Plugins is under development, so the API may change and shed parts as time goes on, additionally the Plugin API as a whole is unstable, currently at version "0.1.0-alpha".
6
+
7
+### Basic Plugins
8
+#### Hello World!  
9
+  To start off with we will make the most basic plugin possible, this plugin will only consist of two lines, here is the code
10
+```Python
11
+import plugins
12
+
13
+plugins.CreatePlugin()
14
+```
15
+
16
+The last line is where the magic happens, it calls the function `CreatePlugin()` with no arguments. Doing that creates a plugin with no name, commands, or version information, so it won't appear anywhere but the logs. So let's make things a bit more interesting and add a name and version:
17
+
18
+```Python
19
+import plugins
20
+
21
+plugins.CreatePlugin(name="Hello World", version="1.0.0")
22
+```
23
+
24
+As you can guess this creates a plugin with a name of "Hello World" and a version of "1.0.0". The version itself can be anything, although a string is generally expected. This plugin has no commands, so let's remedy that. 
25
+
26
+```Python
27
+import plugins
28
+
29
+@plugins.Command("hello", "Say Hello!"))
30
+def hello_world(client, message):
31
+    print("Hello World!")
32
+
33
+plugins.CreatePlugin(name="Hello World", version="1.0.0", commands=[hello_world])
34
+```
35
+
36
+This is now quite a bit more complex and we have quite a few new lines, so let's break it down piece by piece. Let's start with the command part of it:
37
+```Python
38
+@plugins.Command("hello", "Say Hello!")
39
+def hello_world(client, message):
40
+    print("Hello World!")
41
+```
42
+
43
+This section effectively has two parts: The Command Creation and the actual command function. Let's focus on the decorator for now:
44
+
45
+```Python
46
+@plugins.Command("hello", "Say Hello!")
47
+```
48
+This part is a simple decorator that takes in two arguments, the command Name and the command Help Text. The command Name is what the user types to execute a command, in this case it is `hello`, this is case-insensitive for Basic Plugins, so you don't need to worry about case. The next part is the command's Help Text, which is what is returned when another plugin requests that plugins help text (so, for example, a `help` command is issued). In this case it's "Say Hello", however it can be anything that is a string (or `None`, but we will cover that later). This decorates the function and sets it up for being called and used by the plugin we create, and also by the bot to fit what it expects.
49
+
50
+The next part is the actual code that runs when someone does the command:
51
+```Python
52
+def hello_world(client, message):
53
+    print("Hello World!")
54
+```
55
+What this does is rather self-explanitory, when the function is called it is passed in the bot object and the message object. Both of these are constructs of `discord.py`, and as such it is recommended you read through that documentation as well, which is out of the scope of this tutorial. Other than that, this is rather straight forward and thus leads us to our next part.
56
+
57
+```Python
58
+plugins.CreatePlugin(name="Hello World", version="1.0.0", commands=[hello_world])
59
+```
60
+This is rather similar to what we are used to, but it has one additional part to it, the `commands=[hello_world]` part. This parts passes in a list of functions to the plugin, these functions are what are checked and called when the command executes. 
61
+
62
+However let's change this to be a little more useful, in this we will simply be sending a message back, this time to discord itself, the change is simple and we won't go into too much detail here as it uses discord.py's API to send messages, the change is simple replace the `print("Hello World!")` line with this:
63
+```Python
64
+yield from client.send_message(message.channel, "Hello World!")
65
+```
66
+
67
+You can also do this if you are on Python 3.5+
68
+```Python
69
+await client.send_message(message.channel, "Hello World!")
70
+```
71
+
72
+With this you can make almost any kind of basic plugin, but there is a little bit more information needed before hand, what if you want to create undocumented commands?
73
+
74
+#### Secret Commands  
75
+  As we went over in the above section, the way to make commands is pretty straight forward, but let's say you have a command, but you don't want it to be documented by the plugin? Well we have a solution for that, when you use the decorator pass in `None` for the Help Text, a Basic Plugin will not report any help text back for that command at all, so not even the command will be listed.
76
+
77
+### Complex Plugins   
78
+[TO BE WRITTEN]

Loading…
Cancel
Save