diff options
| -rw-r--r-- | README.md | 9 | ||||
| -rw-r--r-- | docs/Commands.md | 175 | ||||
| -rw-r--r-- | docs/Options.md | 210 | ||||
| -rwxr-xr-x | generate_docs.py | 71 |
4 files changed, 461 insertions, 4 deletions
@@ -120,7 +120,7 @@ tokens separated by commas. Commands and options -------------------- -See all available options with descriptions: +For the available options see [docs/Options.md](docs/Options.md) or run this command: ``` /set slack ``` @@ -128,15 +128,16 @@ See all available options with descriptions: Most options require that you reload the script with `/python reload slack` after changing it to take effect. -See all available commands with descriptions: +For the available commands see [docs/Commands.md](docs/Commands.md) or run this command: ``` /slack help ``` In addition to the commands listed with `/slack help`, most normal IRC commands, like `/join`, `/part`, `/query`, `/msg`, `/me`, `/topic`, `/away` and -`/whois` work normally. See WeeChat's documentation or `/help <cmd>` if you are -unfamiliar with these. +`/whois` work normally. See [WeeChat's +documentation](https://weechat.org/files/doc/stable/weechat_user.en.html) or +`/help <cmd>` if you are unfamiliar with these. There are also some special messages you can send: diff --git a/docs/Commands.md b/docs/Commands.md new file mode 100644 index 0000000..51523ff --- /dev/null +++ b/docs/Commands.md @@ -0,0 +1,175 @@ +# Commands + +These are the commands made available by this script. In In addition to +these commands, most normal IRC commands, like `/join`, `/part`, +`/query`, `/msg`, `/me`, `/topic`, `/away` and `/whois` work normally. +See [WeeChat's +documentation](https://weechat.org/files/doc/stable/weechat_user.en.html) +or `/help <cmd>` if you are unfamiliar with these. + +## Available commands: + +### away + +``` +/slack away +``` + +Sets your status as 'away'. + +### back + +``` +/slack back +``` + +Sets your status as 'back'. + +### channels + +``` +/slack channels +``` + +List the channels in the current team. + +### distracting + +``` +/slack distracting +``` + +Add or remove the current channel from distracting channels. You can hide +or unhide these channels with /slack nodistractions. + +### help + +``` +/slack help +``` + +Print help for /slack commands. + +### hide + +``` +/hide +``` + +Hide the current channel if it is marked as distracting. + +### label + +``` +/label <name> +``` + +Rename a thread buffer. Note that this is not permanent. It will only last +as long as you keep the buffer and wee-slack open. + +### linkarchive + +``` +/slack linkarchive [message_id] +``` + +Place a link to the channel or message in the input bar. +Use cursor or mouse mode to get the id. + +### mute + +``` +/slack mute +``` + +Toggle mute on the current channel. + +### nodistractions + +``` +/slack nodistractions +``` + +Hide or unhide all channels marked as distracting. + +### register + +``` +/slack register +``` + +Register a Slack team in wee-slack. + +### rehistory + +``` +/rehistory +``` + +Reload the history in the current channel. + +### reply + +``` +/reply <count/message_id> <text> +``` + +Reply in a thread on the message. Specify either the message id +or a count upwards to the message from the last message. + +### showmuted + +``` +/slack showmuted +``` + +List the muted channels in the current team. + +### slash + +``` +/slack slash /customcommand arg1 arg2 arg3 +``` + +Run a custom slack command. + +### status + +``` +/slack status [emoji [status_message]] +``` + +Lets you set your Slack Status (not to be confused with away/here). + +### talk + +``` +/slack talk <user>[,<user2>[,<user3>...]] +``` + +Open a chat with the specified user(s). + +### thread + +``` +/thread <message_id> +``` + +Open the thread for the message. + +### upload + +``` +/slack upload <filename> +``` + +Uploads a file to the current buffer. + +### users + +``` +/slack users +``` + +List the users in the current team. + diff --git a/docs/Options.md b/docs/Options.md new file mode 100644 index 0000000..7a7dc3d --- /dev/null +++ b/docs/Options.md @@ -0,0 +1,210 @@ +# Options + +You can set these options by using: + +``` +/set plugins.var.python.slack.option_name value +``` + +You can also see all the options and set them them interactively by running `/fset slack`. + +Note that the default value will be shown as an empty string in weechat. +The actual default values are listed below. + +Most options require that you reload the script with `/python reload +slack` after changing it to take effect. + +## Available options: + +### color_reaction_suffix + +**Default:** `darkgray` + +**Description:** Color to use for the [:wave:(@user)] suffix on messages that have reactions attached to them. + +### unfurl_ignore_alt_text + +**Default:** `false` + +**Description:** When displaying ("unfurling") links to channels/users/etc, ignore the "alt text" present in the message and instead use the canonical name of the thing being linked to. + +### shared_name_prefix + +**Default:** `%` + +**Description:** The prefix of buffer names for shared channels. + +### send_typing_notice + +**Default:** `true` + +**Description:** Alert Slack users when you are typing a message in the input bar (Requires reload) + +### map_underline_to + +**Default:** `_` + +**Description:** When sending underlined text to slack, use this formatting character for it. The default ("_") sends it as italics. Use "*" to send bold instead. + +### slack_api_token + +**Default:** `INSERT VALID KEY HERE!` + +**Description:** List of Slack API tokens, one per Slack instance you want to connect to. See the README for details on how to get these. + +### render_italic_as + +**Default:** `italic` + +**Description:** When receiving bold text from Slack, render it as this in weechat. If your terminal lacks italic support, consider using "underline" instead. + +### switch_buffer_on_join + +**Default:** `true` + +**Description:** When /joining a channel, automatically switch to it as well. + +### debug_level + +**Default:** `3` + +**Description:** Show only this level of debug info (or higher) when debug_mode is on. Lower levels -> more messages. + +### color_edited_suffix + +**Default:** `095` + +**Description:** Color to use for (edited) suffix on messages that have been edited. + +### debug_mode + +**Default:** `false` + +**Description:** Open a dedicated buffer for debug messages and start logging to it. How verbose the logging is depends on log_level. + +### group_name_prefix + +**Default:** `&` + +**Description:** The prefix of buffer names for groups (private channels). + +### show_buflist_presence + +**Default:** `true` + +**Description:** Display a `+` character in the buffer list for present users. + +### auto_open_threads + +**Default:** `false` + +**Description:** Automatically open threads when mentioned or inresponse to own messages. + +### server_aliases + +**Default:** `` + +**Description:** A comma separated list of `subdomain:alias` pairs. The alias will be used instead of the actual name of the slack (in buffer names, logging, etc). E.g `work:no_fun_allowed` would make your work slack show up as `no_fun_allowed` rather than `work.slack.com`. + +### colorize_private_chats + +**Default:** `false` + +**Description:** Whether to use nick-colors in DM windows. + +### never_away + +**Default:** `false` + +**Description:** Poke Slack every five minutes so that it never marks you "away". + +### render_bold_as + +**Default:** `bold` + +**Description:** When receiving bold text from Slack, render it as this in weechat. + +### record_events + +**Default:** `false` + +**Description:** Log all traffic from Slack to disk as JSON. + +### background_load_all_history + +**Default:** `false` + +**Description:** Load history for each channel in the background as soon as it opens, rather than waiting for the user to look at it. + +### external_user_suffix + +**Default:** `*` + +**Description:** The suffix appended to nicks to indicate external users. + +### distracting_channels + +**Default:** `` + +**Description:** List of channels to hide. + +### color_buflist_muted_channels + +**Default:** `darkgray` + +**Description:** Color to use for muted channels in the buflist + +### slack_timeout + +**Default:** `20000` + +**Description:** How long (ms) to wait when communicating with Slack. + +### thread_messages_in_channel + +**Default:** `false` + +**Description:** When enabled shows thread messages in the parent channel. + +### unfurl_auto_link_display + +**Default:** `both` + +**Description:** When displaying ("unfurling") links to channels/users/etc, determine what is displayed when the text matches the url without the protocol. This happens when Slack automatically creates links, e.g. from words separated by dots or email addresses. Set it to "text" to only display the text written by the user, "url" to only display the url or "both" (the default) to display both. + +### short_buffer_names + +**Default:** `false` + +**Description:** Use `foo.#channel` rather than `foo.slack.com.#channel` as the internal name for Slack buffers. Overrides server_aliases. + +### show_reaction_nicks + +**Default:** `false` + +**Description:** Display the name of the reacting user(s) alongside each reactji. + +### color_thread_suffix + +**Default:** `lightcyan` + +**Description:** Color to use for the [thread: XXX] suffix on messages that have threads attached to them. + +### channel_name_typing_indicator + +**Default:** `true` + +**Description:** Change the prefix of a channel from # to > when someone is typing in it. Note that this will (temporarily) affect the sort order if you sort buffers by name rather than by number. + +### muted_channels_activity + +**Default:** `personal_highlights` + +**Description:** Control which activity you see from muted channels, either none, personal_highlights, all_highlights or all. none: Don't show any activity. personal_highlights: Only show personal highlights, i.e. not @channel and @here. all_highlights: Show all highlights, but not other messages. all: Show all activity, like other channels. + +### unhide_buffers_with_activity + +**Default:** `false` + +**Description:** When activity occurs on a buffer, unhide it even if it was previously hidden (whether by the user or by the distracting_channels setting). + diff --git a/generate_docs.py b/generate_docs.py new file mode 100755 index 0000000..0280572 --- /dev/null +++ b/generate_docs.py @@ -0,0 +1,71 @@ +#!/usr/bin/python2 +# -*- coding: utf-8 -*- + +from __future__ import print_function +from __future__ import unicode_literals +from textwrap import dedent +import wee_slack + +cmds = wee_slack.EventRouter().cmds +options = wee_slack.PluginConfig.default_settings + +with open('docs/Commands.md', 'w') as file_cmds: + file_cmds.write(dedent(""" + # Commands + + These are the commands made available by this script. In In addition to + these commands, most normal IRC commands, like `/join`, `/part`, + `/query`, `/msg`, `/me`, `/topic`, `/away` and `/whois` work normally. + See [WeeChat's + documentation](https://weechat.org/files/doc/stable/weechat_user.en.html) + or `/help <cmd>` if you are unfamiliar with these. + + ## Available commands: + + """).lstrip()) + + for name, cmd in sorted(cmds.items()): + doc = dedent(cmd.__doc__ or '').strip() + command, helptext = doc.split('\n', 1) + file_cmds.write(dedent(""" + ### {} + + ``` + {} + ``` + + {} + + """).lstrip().format(name, command, helptext)) + +with open('docs/Options.md', 'w') as file_options: + file_options.write(dedent(""" + # Options + + You can set these options by using: + + ``` + /set plugins.var.python.slack.option_name value + ``` + + You can also see all the options and set them them interactively by running `/fset slack`. + + Note that the default value will be shown as an empty string in weechat. + The actual default values are listed below. + + Most options require that you reload the script with `/python reload + slack` after changing it to take effect. + + ## Available options: + + """).lstrip()) + + for name, option in options.items(): + file_options.write(dedent(""" + ### {} + + **Default:** `{}` + + **Description:** {} + + """).lstrip().format(name, option.default, option.desc)) |