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 --- docs/configuration.rst | 195 +++++++++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 1 + 2 files changed, 196 insertions(+) create mode 100644 docs/configuration.rst (limited to 'docs') 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 -- cgit v1.2.3