From 880fd5497abc0da90911ae4c479c0015eb06324a Mon Sep 17 00:00:00 2001 From: Eeshan Garg Date: Fri, 24 Nov 2017 19:32:20 -0330 Subject: [PATCH] markdown: Add indented versions of multi-line Markdown macros. This is part of our efforts to change our integrations/webhooks docs to follow the same sort of numbered-list format as our /help docs. In order to indicate that paragraphs separated by newlines are part of the same numbered-list point, every paragraph must be indented 4 spaces. --- .../change-zulip-config-file-indented.md | 13 ++++++++++++ .../create-bot-construct-url-indented.md | 20 +++++++++++++++++++ .../git-webhook-url-with-branches-indented.md | 4 ++++ .../webhook-url-with-bot-email-indented.md | 7 +++++++ tools/linter_lib/custom_check.py | 2 ++ 5 files changed, 46 insertions(+) create mode 100644 templates/zerver/help/include/change-zulip-config-file-indented.md create mode 100644 templates/zerver/help/include/create-bot-construct-url-indented.md create mode 100644 templates/zerver/help/include/git-webhook-url-with-branches-indented.md create mode 100644 templates/zerver/help/include/webhook-url-with-bot-email-indented.md diff --git a/templates/zerver/help/include/change-zulip-config-file-indented.md b/templates/zerver/help/include/change-zulip-config-file-indented.md new file mode 100644 index 0000000000..cefc63889f --- /dev/null +++ b/templates/zerver/help/include/change-zulip-config-file-indented.md @@ -0,0 +1,13 @@ + On your {{ settings_html|safe }}, create a bot for + {{ integration_display_name }}. + + Next, open + `integrations/{{ integration_name }}/zulip_{{ integration_name }}_config.py` + with your favorite editor, and change the following lines to specify the + email address and API key for your {{ integration_display_name }} bot: + + ``` + ZULIP_USER = "{{ integration_name }}-bot@example.com" + ZULIP_API_KEY = "0123456789abcdef0123456789abcdef" + ZULIP_SITE = "{{ api_url }}" + ``` diff --git a/templates/zerver/help/include/create-bot-construct-url-indented.md b/templates/zerver/help/include/create-bot-construct-url-indented.md new file mode 100644 index 0000000000..12f970aa3a --- /dev/null +++ b/templates/zerver/help/include/create-bot-construct-url-indented.md @@ -0,0 +1,20 @@ + Next, on your {{ settings_html|safe }}, + [create a bot](/help/add-a-bot-or-integration) for + {{ integration_display_name }}. Make sure that you select + **Incoming webhook** as the **Bot type**: + + ![](/static/images/help/bot_types.png) + + The API keys for "Incoming webhook" bots are limited to only + sending messages via webhooks. Thus, this bot type lessens + the security risks associated with exposing the bot's API + key to third-party services. + + Construct the URL for the {{ integration_display_name }} + bot using the bot API key and stream name: + + {!webhook-url.md!} + + Modify the parameters of the URL above, where `api_key` is the API key + of your Zulip bot, and `stream` is the stream name you want the + notifications sent to. diff --git a/templates/zerver/help/include/git-webhook-url-with-branches-indented.md b/templates/zerver/help/include/git-webhook-url-with-branches-indented.md new file mode 100644 index 0000000000..5bba6db1ae --- /dev/null +++ b/templates/zerver/help/include/git-webhook-url-with-branches-indented.md @@ -0,0 +1,4 @@ + You can also limit the branches you receive notifications for by + specifying them in a comma-separated list at the end of the URL, + like so: + `{{ api_url }}{{ integration_url }}?api_key=abcdefgh&stream={{ recommended_stream_name }}&branches=master,development` diff --git a/templates/zerver/help/include/webhook-url-with-bot-email-indented.md b/templates/zerver/help/include/webhook-url-with-bot-email-indented.md new file mode 100644 index 0000000000..2892628727 --- /dev/null +++ b/templates/zerver/help/include/webhook-url-with-bot-email-indented.md @@ -0,0 +1,7 @@ + In the URL field, enter: + + `{{ external_uri_scheme }}bot_email:bot_api_key@{{ api_url_scheme_relative }}{{ integration_url }}` + + Replace `bot_email` and `bot_api_key` above with the URL-encoded email + address and API key of the bot. To URL-encode the email address, you + just need to replace `@` in the bot's email address with `%40`. diff --git a/tools/linter_lib/custom_check.py b/tools/linter_lib/custom_check.py index 1f1f53d27d..66a5a65c4b 100644 --- a/tools/linter_lib/custom_check.py +++ b/tools/linter_lib/custom_check.py @@ -699,6 +699,8 @@ def build_custom_checkers(by_lang): "templates/zerver/integrations/perforce.md", # Has some example code that could perhaps be wrapped "templates/zerver/api/webhook-walkthrough.md", + # This macro has a long indented URL + "templates/zerver/help/include/git-webhook-url-with-branches-indented.md", } for fn in by_lang['md']: max_length = None