Merge branch 'master' into devel

docs/README.md

@@ -8,3 +8,5 @@ This folder contains general documentation for PyLink IRC services.
 - [PyLink Relay Tutorial & Oper Guide](pylink-opers.md)
 - [Automode & Exttargets Guide](automode.md)
 - [Developer documentation](technical/)
+
+There is also a (WIP) Doxygen-powered API reference at https://pylink.github.io/

docs/technical/README.md

@@ -18,7 +18,8 @@ PyLink is an a modular, plugin-based IRC services framework. It uses swappable p
 - [PyLink hooks reference](hooks-reference.md)
 - [Supported named channel modes](channel-modes.csv)
 - [Supported named user modes](user-modes.csv)
+- [Services bot API/Creating your own service bots](services-api.md)
 
 ### Future topics (not yet available)
 - [Writing tests for PyLink modules](writing-tests.md)
-- [Services bot API/Creating your own service bots](services-api.md)
+

docs/technical/doxygen.sh

@@ -0,0 +1,15 @@
+#!/bin/bash
+# Runs Doxygen on PyLink.
+
+# Note: to change the outpuit path, doxygen.conf also has to be updated too!
+OUTDIR="../../../pylink.github.io"
+
+if [ ! -d "$OUTDIR" ]; then
+	echo "Git clone https://github.com/PyLink/pylink.github.io to $OUTDIR and then rerun this script."
+	exit 1
+fi
+
+CURDIR="$(pwd)"
+doxygen doxygen.conf
+cp -R html/* "$OUTDIR"
+rm -r "html/"

docs/technical/services-api.md

@@ -0,0 +1,61 @@
+# PyLink Services Bot API
+
+Starting with PyLink 0.9.x, a services bot API was introduced to make writing custom services slightly easier. PyLink's Services API automatically connects service bots, and handles rejoin on kick/kill all by itself, meaning less code is needed per plugin to have functional service bots.
+
+## Creating new services
+
+Services can be created (registered) using code similar to the following in a plugin:
+
+```python
+
+from pylinkirc import utils, world
+
+# Description is optional (though recommended), and usually around a sentence or two.
+desc = "Optional description of servicenick, in sentence form."
+
+# First argument is the internal service name.
+# utils.registerService() returns a utils.ServiceBot instance, which can also be found
+# by calling world["myservice"].
+myservice = utils.registerService("myservice", desc=desc)
+```
+
+`utils.registerService()` passes its arguments directly to the `utils.ServiceBot` class constructor, which in turn supports the following options:
+
+- **`name`** - defines the service name (mandatory)
+- `default_help` - Determines whether the default HELP command should be used for the service. Defaults to True.
+- `default_list` - Determines whether the default LIST command should be used for the service. Defaults to True.
+- `nick`, `ident` - Sets the default nick and ident for the service bot. If not given, these simply default to the service name.
+- `manipulatable` - Determines whether the bot is marked manipulatable. Only manipulatable clients can be force joined, etc. using PyLink commands. Defaults to False.
+- `extra_channels` - Defines a dict mapping network names to a set of channels that the bot should autojoin on that network.
+- `desc` - Sets the command description of the service. This is shown in the default HELP command if enabled.
+
+### Getting the UID of a bot
+
+Should you want to get the UID of a service bot on a specific server, use `myservice.uids.get('irc.name')`
+
+### Setting channels to join
+
+All services bots wil automatically join the autojoin channels configured for a specific network, if any.
+
+However, plugins can modify the autojoin entries of a specific bot by adding items to the `myservice.extra_channels` channel set. After sending `irc.proto.join(...)` using the service bot's UID as a source, the bot should permanently remain on that channel throughout KILLs or disconnects.
+
+## Removing services on unload
+
+All plugins using the services API **MUST** have a `die()` function that unregisters all services that they've created. A simple example would be in the `games` plugin:
+
+```python
+def die(irc):
+    utils.unregisterService('games')
+```
+
+## Service bots and commands
+
+Commands for service bots and commands for the main PyLink bot have two main differences.
+
+1) Commands for service bots are bound using `myservice.add_cmd(cmdfunc, 'cmdname')` instead of `utils.add_cmd(...)`
+
+2) Replies for service bot commands are sent using `myservice.reply(irc, text)` instead of `irc.reply(...)`
+
+### Featured commands
+
+Commands for service bots can also be marked as *featured*, which shows it with its command arguments in the default `LIST` command. To mark a command as featured, use `myservice.add_cmd(cmdfunc, 'cmdname', featured=True)`.

pylink

@@ -10,7 +10,8 @@ try:
 except ImportError:
     sys.stderr.write("ERROR: Failed to import PyLink main module (pylinkirc.world).\n\nIf you are "
                      "running PyLink from source, please install PyLink first using 'python3 "
-                     "setup.py install [--user]'\n")
+                     "setup.py install' (global install) or 'python3 setup.py install --user'"
+                     " (local install)\n")
     sys.exit(1)
 from pylinkirc import conf, __version__
 

utils.py

@@ -185,7 +185,7 @@ class ServiceBot():
     PyLink IRC Service class.
     """
 
-    def __init__(self, name, default_help=True, default_request=False, default_list=True,
+    def __init__(self, name, default_help=True, default_list=True,
                  nick=None, ident=None, manipulatable=False, extra_channels=None,
                  desc=None):
         # Service name
@@ -220,10 +220,6 @@ class ServiceBot():
         if default_help:
             self.add_cmd(self.help)
 
-        if default_request:
-            self.add_cmd(self.request)
-            self.add_cmd(self.remove)
-
         if default_list:
             self.add_cmd(self.listcommands, 'list')
 
@@ -344,12 +340,6 @@ class ServiceBot():
         else:
             self._show_command_help(irc, command)
 
-    def request(self, irc, source, args):
-        self.reply(irc, "Request command stub called.")
-
-    def remove(self, irc, source, args):
-        self.reply(irc, "Remove command stub called.")
-
     def listcommands(self, irc, source, args):
         """takes no arguments.