integration-docs: Update the RSS integration doc. #872
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -1,26 +1,81 @@ | ||||||
| # Zulip RSS Integration | ||||||
|
|
||||||
| Get updates from RSS feeds in Zulip! | ||||||
|
|
||||||
| !!! tip "" | ||||||
|
|
||||||
| [The Zapier integration][1] is usually a simpler way to | ||||||
| integrate RSS with Zulip. | ||||||
|
|
||||||
| [1]: ./zapier | ||||||
|
|
||||||
| {start_tabs} | ||||||
|
|
||||||
| 1. {!create-an-incoming-webhook.md!} | ||||||
|
|
||||||
| Download the `zuliprc` configuration file of your bot by clicking the | ||||||
| download (<i class="fa fa-download"></i>) icon under the bot's name, and | ||||||
| save to `~/.zuliprc`. | ||||||
|
|
||||||
| 1. {!download-python-bindings.md!} | ||||||
|
|
||||||
| 1. {!install-requirements.md!} | ||||||
|
|
||||||
| 1. Create a file containing RSS feed URLs, with one URL per line, at | ||||||
| `~/.cache/zulip-rss/rss-feeds`. To use a different location, pass the | ||||||
| `--feed-file` [option](#configuration-options) to the integration | ||||||
Niloth-p marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| script. | ||||||
|
|
||||||
| 1. Run the bot to send summaries of RSS entries from your favorite feeds, | ||||||
| with the command: | ||||||
|
|
||||||
| `{{ integration_path }}/rss-bot` | ||||||
|
|
||||||
| 1. Optionally, pass command-line arguments to re-configure the integration. | ||||||
| See [the configuration options](#configuration-options) below. | ||||||
|
There was a problem hiding this comment.
Suggested change
There was a problem hiding this comment. The reason for having the "Optionally" word, and mention the "list of options" is that there are some integrations that require all of their supported command-line arguments. We're trying to say that these command-line arguments are not necessary, but if the user wants to configure it further, they can. And the full list of options is available below, but the user can choose to use some of those options without using the rest. I've retained the "Optionally" word, but rephrased the link sentence as suggested. |
||||||
|
|
||||||
| ``` | ||||||
| {{ integration_path }}/rss-bot \ | ||||||
| --feed-file="home/user/zulip-rss/rss-feeds" \ | ||||||
| --data-dir="home/user/zulip-rss" \ | ||||||
| --stream="news" \ | ||||||
| --topic="rss" \ | ||||||
| --unwrap --math | ||||||
| ``` | ||||||
|
|
||||||
| 1. Configure a crontab entry to keep the integration running. | ||||||
|
|
||||||
| This sample crontab entry processes feeds stored in the default | ||||||
| location and posts to the "rss" topic in the **#news** channel every 5 | ||||||
| minutes: | ||||||
|
|
||||||
| `*/5 * * * * {{ integration_path }}/rss-bot --stream="news" --topic="rss"` | ||||||
|
|
||||||
| {end_tabs} | ||||||
|
|
||||||
| {!congrats.md!} | ||||||
|
|
||||||
|  | ||||||
|
|
||||||
| ### Configuration options | ||||||
|
|
||||||
| The integration script accepts the following command-line arguments. | ||||||
|
|
||||||
| - `--feed-file`: The path to the file containing the RSS feed URLs. The | ||||||
| default location is `~/.cache/zulip-rss/rss-feeds`. | ||||||
|
|
||||||
| - `--data-dir`: The directory where feed metadata is stored. The default | ||||||
| location is `~/.cache/zulip-rss`. | ||||||
|
|
||||||
| - `--stream`: The name of the Zulip channel you want to receive | ||||||
| notifications in. By default, messages are sent to the **#rss** channel. | ||||||
|
|
||||||
| - `--topic`: The name of the topic to which the RSS entries will be posted. | ||||||
| By default, for each RSS feed URL specified, the feed's title is used for | ||||||
| the topic name. | ||||||
|
|
||||||
| - `--unwrap`: This option converts word-wrapped paragraphs in the message | ||||||
| content into single lines. | ||||||
|
|
||||||
| - `--math`: This option converts `$` in the message content to `$$`, for | ||||||
| KaTeX processing. | ||||||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is this only if you're OK with all the messages going to the same topic? If so, it should be something like:
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Not particularly, Zapier can send DMs or construct the topic name from the payload too.
I think the direct integration may be preferred by folks who want to customize the integration, or use the
--unwrapor--mathoptions or wish to send DMs without sharing their credentials with Zapier.