Add more documentation about plugin configuration

7 files changed, 69 insertions, 17 deletions

diff --git a/docs/_static/brackets.png b/docs/_static/brackets.png
new file mode 100644
index 0000000..84121ce
--- /dev/null
+++ b/docs/_static/brackets.png
diff --git a/docs/_static/hidePush.png b/docs/_static/hidePush.png
new file mode 100644
index 0000000..dfe3813
--- /dev/null
+++ b/docs/_static/hidePush.png
diff --git a/docs/_static/preventIssueNameSpam.png b/docs/_static/preventIssueNameSpam.png
new file mode 100644
index 0000000..3c70764
--- /dev/null
+++ b/docs/_static/preventIssueNameSpam.png
diff --git a/docs/_static/showMilestone.png b/docs/_static/showMilestone.png
new file mode 100644
index 0000000..7c47cd0
--- /dev/null
+++ b/docs/_static/showMilestone.png
diff --git a/docs/_static/theme.png b/docs/_static/theme.png
new file mode 100644
index 0000000..5443216
--- /dev/null
+++ b/docs/_static/theme.png
diff --git a/docs/configuration.rst b/docs/configuration.rst
index 9001eac..1a9666a 100644
--- a/docs/configuration.rst
+++ b/docs/configuration.rst
@@ -11,7 +11,43 @@ for you to play with, switchable globally, per channel, or per repository.
 Changing the configuration
 --------------------------
 
-# TODO
+The configuration variables for the plugin are managed by Supybot's native
+configuration plugin, which means there is nothing different compared to any
+other Supybot option or plugin.
+
+All configuration options naturally reside in the ``supybot.plugins.Github``
+group (note that option names are case-insensitive).
+
+You can easily manipulate config options using your bot's ``config`` command:
+
+>>> config list plugins.github
+#allowArbitraryMessages, #alwaysShowForcedPushes, #brackets, #hidePush, #hideURL, ...
+
+>>> config plugins.github.theme
+default
+
+>>> config plugins.github.theme compact # To set the theme to `compact`
+The operation succeeded.
+
+You can also change most of the configuration values for each channel:
+
+>>> config channel "#main" plugins.github.hidePush true
+The operation succeeded.
+
+Changing the configuration in the URL
+`````````````````````````````````````
+
+Supybot-github also allows specifying most configuration options in the web hook
+URL, provided that the :ref:`disallowConfigOverride <disallowConfigOverride-option>`
+option is set to `False`. For example, if your default webhook URL is
+``http://example.com:8093/``, you can request that messages are sent in the
+``##commits`` channel, and set the configuration options ``shortURL=False``
+and ``theme=compact`` by switching to this URL::
+
+  http://example.com:8093/++commits/shortURL=False/theme=compact
+
+Note that you can use the ``+``, ``~``, ``&`` and ``^`` symbols instead of the
+normal ``#`` IRC channel prefix, to ensure that URLs work properly.
 
 Available configuration values
 ------------------------------
@@ -42,7 +78,8 @@ Available configuration values
   Whether to hide the `User pushed .. commits into ...` message shown when a
   push is received
 
-  .. TODO: Add an image
+  .. image:: _static/hidePush.png
+     :scale: 75
 
   Force-pushes will still be shown regardless of this settings, if
   ``alwaysShowForcedPushes`` is set to True.
@@ -53,7 +90,8 @@ Available configuration values
 ``theme``
   The name of the theme that will be used to style IRC messages.
 
-  .. TODO: Add an image
+  .. image:: _static/theme.png
+     :scale: 50
 
   Only two themes are currently available, ``default`` and ``compact``, which
   is based on the default theme, with less verbose and more organised commit
@@ -63,7 +101,7 @@ Available configuration values
   ``DefaultTheme.py`` classes as examples. Themes are expected to be stored in
   the ``local/theme/`` directory.
 
-  :Default value: `default`
+  :Default value: `default` (who would expect)
   :Type: String
 
 ``showMergedCommits``
@@ -73,7 +111,7 @@ Available configuration values
   :Default value: `False`
   :Type: Boolean
 
-  ``showSuccessfulBuildMessages``
+``showSuccessfulBuildMessages``
   Whether to show build messages for non-failing builds on CI services, such
   as Travis and AppVeyor. Setting to ``never`` will not show any message when
   a build is successful, setting to ``always`` will show all success messages,
@@ -89,18 +127,19 @@ Available configuration values
   be useful if your IRC client considers the default parentheses part of the
   URL, resulting in wrong paths and 404 errors.
 
-  .. TODO: Add an image
+  .. image:: _static/brackets.png
+     :scale: 75
 
   The ``brackets`` option is a string whose left half is the left bracket that
   will be placed before the URL, and whose right half is the right URL bracket.
   The middle character, if there is one, is ignored. This convention has the
   limitation that the left and right parts of the URL must have the same length.
   To bypass that, you can use the capital letter `M` to separate the string into
-  left and right:
+  left and right.
+
+  **Examples:**
 
   =============  =================================
-                      Examples
-  ------------------------------------------------
   ``brackets``                  URL
   =============  =================================
   *space*        ``https://git.io/v2tq4``
@@ -113,11 +152,18 @@ Available configuration values
   ``->  M``      ``-> https://git.io/v2tq4``
   =============  =================================
 
+  *NOTE:* Don't forget to quote (`"`) your bracket string when setting the
+  configuration value on Supybot
+
+  :Default value: ``( )``
+  :Type: String
+
 ``showMilestone``
   Shows the name of the issue's milestone, when a notification is shown for
   any issue update (if the milestone is specified).
 
-  .. TODO: Add an image
+  .. image:: _static/showMilestone.png
+     :scale: 75
 
   Milestone updates will still be shown if this is set to False.
 
@@ -144,6 +190,9 @@ Available configuration values
   time (e.g. when multiple labels are added), the issue name and URL will only
   be sent once, to reduce clutter.
 
+  .. image:: _static/preventIssueNameSpam.png
+     :scale: 75
+
   :Default value: `True`
   :Type: Boolean
 
@@ -176,20 +225,23 @@ Available configuration values
   :Type: Boolean
   :Scope: `Global`
 
+.. _disallowConfigOverride-option:
+
 ``disallowConfigOverride``
   Whether to ignore any configuration options provided in the HTTP hook URL
 
   If the ``disallowChannelOverride`` option is set to True, URLs will still be
   able to specify the notification's IRC channel, regardless of this setting.
 
-  :Default value: ``True``
+  :Default value: `True`
   :Type: Boolean
   :Scope: `Global`
 
 ``allowArbitraryMessages``
   Whether to allow raw messages and colours to be sent to channels using HTTP
-  (this does not bypass other security options)
+  (this does not bypass other security options). Useful when you want to use a
+  tool that reports results on IRC via your supybot.
 
-  :Default value: ``False``
+  :Default value: `False`
   :Type: Boolean
   :Scope: `Channel`
diff --git a/local/handler/GithubHandler.py b/local/handler/GithubHandler.py
index 19fe2e5..e767e49 100644
--- a/local/handler/GithubHandler.py
+++ b/local/handler/GithubHandler.py
@@ -83,10 +83,10 @@ class GithubHandler(BaseHTTPServer.BaseHTTPRequestHandler):
             if i == 1 and requireCode:
                 receivedcode = part
 
-            part = part.replace('+','#');
-            part = part.replace('~','#');
-            part = part.replace('&','#');
-            part = part.replace('^','#');
+            part = part.replace('+','#')
+            part = part.replace('~','#')
+            part = part.replace('&','#')
+            part = part.replace('^','#')
 
             # TODO: Throw out a warning when a URL specifies a configuration
             # value but we don't allow that