From aa94ba150fdb0bd7cec63dae937e0bb52dc1b575 Mon Sep 17 00:00:00 2001 From: kongr45gpen Date: Wed, 4 Jan 2017 03:36:29 +0200 Subject: Add documentation about configuration options --- config.py | 2 +- docs/configuration.rst | 195 +++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 1 + local/handler/GithubHandler.py | 2 + 4 files changed, 199 insertions(+), 1 deletion(-) create mode 100644 docs/configuration.rst 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'): -- cgit v1.2.3