Add documentation about configuration options

4 files changed, 199 insertions, 1 deletions

diff --git a/config.py b/config.py
index 86fd252..9b6eef6 100644
--- a/config.py
+++ b/config.py
@@ -82,7 +82,7 @@ conf.registerChannelValue(Github, 'showIssueEdits',
         """Whether to show a message when an issue is edited"""))
 
 conf.registerChannelValue(Github, 'showPendingStatuses',
-        registry.Boolean(True,
+        registry.Boolean(False,
         """Whether to show a message for a pending status (e.g. a build in progress)"""))
 
 conf.registerChannelValue(Github, 'alwaysShowForcedPushes',
diff --git a/docs/configuration.rst b/docs/configuration.rst
new file mode 100644
index 0000000..9001eac
--- /dev/null
+++ b/docs/configuration.rst
@@ -0,0 +1,195 @@
+.. _configuration:
+
+Configuring supybot-github
+==========================
+
+.. TODO: Update 19->20 when we have enough configuration variables
+
+Supybot-github contains more than nineteen configuration variables available
+for you to play with, switchable globally, per channel, or per repository.
+
+Changing the configuration
+--------------------------
+
+# TODO
+
+Available configuration values
+------------------------------
+``channel``
+  The one IRC channel where notification messages should be sent by default
+  (can be changed in the hook URL, unless the `disallowChannelOverride` option
+  is set to True)
+
+  :Default value: ``#commits``
+  :Type: String
+  :Scope: `Global`
+
+``port``
+  The port which will be used by the HTTP server to receive event information
+  from Github and other services
+
+  :Default value: `8093`
+  :Type: Integer
+  :Scope: `Global`
+
+``shortURL``
+  Whether to use https://git.io/ to make URLs to github pages shorter
+
+  :Default value: `True`
+  :Type: Boolean
+
+``hidePush``
+  Whether to hide the `User pushed .. commits into ...` message shown when a
+  push is received
+
+  .. TODO: Add an image
+
+  Force-pushes will still be shown regardless of this settings, if
+  ``alwaysShowForcedPushes`` is set to True.
+
+  :Default value: `False`
+  :Type: Boolean
+
+``theme``
+  The name of the theme that will be used to style IRC messages.
+
+  .. TODO: Add an image
+
+  Only two themes are currently available, ``default`` and ``compact``, which
+  is based on the default theme, with less verbose and more organised commit
+  notifications.
+
+  You can create your own themes, using the provided ``CompactTheme.py`` and
+  ``DefaultTheme.py`` classes as examples. Themes are expected to be stored in
+  the ``local/theme/`` directory.
+
+  :Default value: `default`
+  :Type: String
+
+``showMergedCommits``
+  Whether to show all the old merged commits when a branch is merged into
+  another branch
+
+  :Default value: `False`
+  :Type: Boolean
+
+  ``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,
+  and setting this to ``change`` will only notify about successful builds, when
+  the previous build was broken (i.e. whenever the build is fixed).
+
+  :Default value: `change`
+  :Possible values: ``never``, ``change``, ``always``
+  :Type: Enum
+
+``brackets``
+  A set of characters to use instead of parentheses to enclose URLs. This may
+  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
+
+  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:
+
+  =============  =================================
+                      Examples
+  ------------------------------------------------
+  ``brackets``                  URL
+  =============  =================================
+  *space*        ``https://git.io/v2tq4``
+  ``()``         ``(https://git.io/v2tq4)``
+  ``[]``         ``[https://git.io/v2tq4]``
+  ``[ ]``        ``[https://git.io/v2tq4]``
+  ``[M]``        ``[https://git.io/v2tq4]``
+  ``--> <--``    ``-->https://git.io/v2tq4<--``
+  ``-->  <--``   ``--> https://git.io/v2tq4 <--``
+  ``->  M``      ``-> https://git.io/v2tq4``
+  =============  =================================
+
+``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
+
+  Milestone updates will still be shown if this is set to False.
+
+  :Default value: `True`
+  :Type: Boolean
+
+``tagShowCommitMsg``
+  When a notification about a new tag is shown, display the message of the
+  commit the tag is pointing to.
+
+  :Default value: `True`
+  :Type: Boolean
+
+``hideURL``
+  Whether to hide URLs for all actions.
+
+  Useful for private repositories
+
+  :Default value: `False`
+  :Type: Boolean
+
+``preventIssueNameSpam``
+  If true, when many messages about the same Github issue are sent at the same
+  time (e.g. when multiple labels are added), the issue name and URL will only
+  be sent once, to reduce clutter.
+
+  :Default value: `True`
+  :Type: Boolean
+
+``showIssueEdits``
+  Whether to send a message when an issue is edited.
+
+  :Default value: `True`
+  :Type: Boolean
+
+``showPendingStatuses``
+  Whether to show a message for a "pending" status update by Github (e.g. when
+  a Travis build starts)
+
+  :Default value: `False`
+  :Type: Boolean
+
+``alwaysShowForcedPushes``
+  Whether to always show force-pushes, regardless of the value of the `hidePush`
+  option.
+
+  :Default value: `True`
+  :Type: Boolean
+
+``disallowChannelOverride``
+  Whether to force all commits to end up in the channel specified by the
+  `channel` configuration option, ignoring the channel specified in the HTTP
+  hook URL
+
+  :Default value: `False`
+  :Type: Boolean
+  :Scope: `Global`
+
+``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``
+  :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)
+
+  :Default value: ``False``
+  :Type: Boolean
+  :Scope: `Channel`
diff --git a/docs/index.rst b/docs/index.rst
index 04d7c43..60e7134 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -59,3 +59,4 @@ Further Reading
    :maxdepth: 2
 
    getting-started
+   configuration
diff --git a/local/handler/GithubHandler.py b/local/handler/GithubHandler.py
index 6a7d075..19fe2e5 100644
--- a/local/handler/GithubHandler.py
+++ b/local/handler/GithubHandler.py
@@ -88,6 +88,8 @@ class GithubHandler(BaseHTTPServer.BaseHTTPRequestHandler):
             part = part.replace('&','#');
             part = part.replace('^','#');
 
+            # TODO: Throw out a warning when a URL specifies a configuration
+            # value but we don't allow that
             if part.startswith("#") and not configValue('disallowChannelOverride'):
                 channel = part
             elif '=' in part and not configValue('disallowConfigOverride'):