docs: add basic service docs (#167)

* add support for multipart url fields * fix docs build script * add basic slack service documentation * add basic gotify service documentation * use sub header for url sections * add basic discord documentation * fix renderers url format * fix gotify docs typos * update hangouts service docs * add custom bool output * add basic iftt service documentation * fix empty username url preview * add basic join service documentation * add basic mattermost service documentation * add basic opsgenie service documentation * add basic pushbullet service documentation * add basic pushover service documentation * sort url path fields by index * add basic rocketchat service documentation * add basic telegram service documentation * add basic zulip service documentation * update teams documentation * fix discord test * linting fixes
containrrr · May 15, 2021 · e156cfd · e156cfd
1 parent 2e5982c
commit e156cfd
Show file tree

Hide file tree

Showing 38 changed files with 371 additions and 140 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -27,7 +27,7 @@ jobs:
             md-toc
 
       - name: Generate service config docs
-        run: sh generate-service-config-docs.sh
+        run: bash generate-service-config-docs.sh
 
       - name: Generate docs
         run: mkdocs build

diff --git a/cli/cmd/docs/docs.go b/cli/cmd/docs/docs.go
@@ -50,7 +50,7 @@ func printDocs(format string, services []string) cli.Result {
 	case "console":
 		renderer = f.ConsoleTreeRenderer{WithValues: false}
 	case "markdown":
-		renderer = f.MarkdownTreeRenderer{}
+		renderer = f.MarkdownTreeRenderer{HeaderPrefix: "### "}
 	default:
 		return cli.InvalidUsage("invalid format")
 	}

diff --git a/docs/services/discord.md b/docs/services/discord.md
@@ -3,25 +3,16 @@
 ## URL Format
 
 Your Discord Webhook-URL will look like this:
-> https://discordapp.com/api/webhooks/__`channel`__/__`token`__  
+
+!!! info ""
+    https://discordapp.com/api/webhooks/__`webhookid`__/__`token`__  
 
 The shoutrrr service URL should look like this:  
-> discord://__`token`__@__`channel`__
-
-## Additional props
-
-*Can be either supplied using the params argument, or through the URL using ?key=value&key=value etc.*.
-
- * **Title**  
-   Type: *string*, Default: _empty_
- * **Username** - Override the webhook default username
-    Type: *string*, Default: _empty_
- * **AvatarURL** - Override the webhook default avatar  
-   Type: *string*, Default: _empty_        
- * **Color** - The color of the left border for plain messages
-   Type: *number*, Default: 0x50D9ff
- * **SplitLines** - Whether to send each line as a separate message item  
-   Type: *boolean*, Default: yes
+
+!!! info ""
+    discord://__`token`__@__`webhookid`__
+
+--8<-- "docs/services/discord/config.md"
 
 ## Creating a webhook in Discord
 

diff --git a/docs/services/email.md b/docs/services/email.md
@@ -1,8 +1,8 @@
 # Email
 
 ## URL Format
-*smtp://__`username`__:__`password`__@__`host`__:__`port`__/?from=__`fromAddress`__&to=__`recipient1`__[,__`recipient2`__,...]*
 
-Props can be either supplied using the params argument, or through the URL using `?key=value&key=value` etc.
+!!! info ""
+    smtp://__`username`__:__`password`__@__`host`__:__`port`__/?from=__`fromAddress`__&to=__`recipient1`__[,__`recipient2`__,...]
 
 --8<-- "docs/services/smtp/config.md"
diff --git a/docs/services/gotify.md b/docs/services/gotify.md
@@ -1,4 +1,18 @@
 # Gotify
 
 ## URL Format
-*gotify://__`gotify-host`__/__`token`__*   
+
+--8<-- "docs/services/gotify/config.md"
+
+## Examples
+
+!!! example "Common usage"
+
+    ```uri
+    gotify://gotify.example.com:443/AzyoeNS.D4iJLVa/?title=Great+News&priority=1
+    ```
+
+!!! example "With subpath"
+    ```uri
+    gotify://example.com:443/path/to/gotify/AzyoeNS.D4iJLVa/?title=Great+News&priority=1
+    ```
diff --git a/docs/services/hangouts.md b/docs/services/hangouts.md
@@ -4,11 +4,13 @@
 
 Your Hangouts Chat Incoming Webhook URL will look like this:
 
-> https://chat.googleapis.com/v1/spaces/FOO/messages?key=bar&token=baz
+!!! info ""
+    https://chat.googleapis.com/v1/spaces/__`FOO`__/messages?key=__`bar`__&token=__`baz`__
 
 The shoutrrr service URL should look like this:
 
-> hangouts://chat.googleapis.com/v1/spaces/FOO/messages?key=bar&token=baz
+!!! info ""
+    hangouts://chat.googleapis.com/v1/spaces/__`FOO`__/messages?key=__`bar`__&token=__`baz`__
 
 In other words the incoming webhook URL with `https` replaced by `hangouts`.
 

diff --git a/docs/services/ifttt.md b/docs/services/ifttt.md
@@ -1,4 +1,8 @@
 # IFTTT
 
 ## URL Format
-*ifttt://__`key`__/?events=__`event1`__[,__`event2`__,...]&value1=__`value1`__&value2=__`value2`__&value3=__`value3`__*
+
+!!! info ""
+    ifttt://__`key`__/?events=__`event1`__[,__`event2`__,...]&value1=__`value1`__&value2=__`value2`__&value3=__`value3`__
+
+--8<-- "docs/services/ifttt/config.md"
diff --git a/docs/services/join.md b/docs/services/join.md
@@ -1,4 +1,21 @@
 # Join
 
 ## URL Format
-*join://shoutrrr:__`api-key`__@join/?devices=__`device1`__[,__`device2`__, ...][&icon=__`icon`__][&title=__`title`__]*    
+
+!!! info ""
+    join://shoutrrr:__`api-key`__@join/?devices=__`device1`__[,__`device2`__, ...][&icon=__`icon`__][&title=__`title`__]
+
+--8<-- "docs/services/join/config.md"
+
+## Guide
+
+1.  Go to the [Join Webapp](https://joinjoaomgcd.appspot.com/) 
+2.  Select your device
+3.  Click **Join API** 
+4.  Your `deviceId` is shown in the top
+5.  Click **Show** next to `API Key` to see your key 
+6.  Your Shoutrrr URL will then be:
+    `join://shoutrrr:`__`api-key`__`@join/?devices=`__`deviceId`__
+
+!!! note ""
+    Multiple `deviceId`s can be combined with a `,` (repeat steps 2-4).
diff --git a/docs/services/mattermost.md b/docs/services/mattermost.md
@@ -2,7 +2,12 @@
 
 ## URL Format
 
-*mattermost://[__`username`__@]__`mattermost-host`__/__`token`__[/__`channel`__]*
+!!! info ""
+    mattermost://[__`username`__@]__`mattermost-host`__/__`token`__[/__`channel`__]
+
+--8<-- "docs/services/mattermost/config.md"
+
+
 
 ## Creating a Webhook in MatterMost
 

diff --git a/docs/services/opsgenie.md b/docs/services/opsgenie.md
@@ -2,6 +2,8 @@
 
 ## URL Format
 
+--8<-- "docs/services/opsgenie/config.md"
+
 ## Creating a REST API endpoint in OpsGenie
 
 1. Open up the Integration List page by clicking on *Settings => Integration List* within the menu
@@ -31,7 +33,7 @@ If you want to, you can pass additional parameters to the `send` function.
 <br/>
 The following example contains all parameters that are currently supported.
 
-```gotemplate
+```go
 service.Send("An example alert message", &types.Params{
     "alias":       "Life is too short for no alias",
     "description": "Every alert needs a description",
@@ -48,12 +50,17 @@ service.Send("An example alert message", &types.Params{
 })
 ```
 
-# Optional parameters
+## Optional parameters
 
 You can optionally specify the parameters in the URL:
-opsgenie://api.opsgenie.com/eb243592-faa2-4ba2-a551q-1afdf565c889?alias=Life+is+too+short+for+no+alias&description=Every+alert+needs+a+description&actions=An+action&tags=["tag1","tag2"]&entity=An+example+entity&source=The+source&priority=P1&user=Dracula&note=Here+is+a+note
+
+!!! info ""
+    opsgenie://api.opsgenie.com/eb243592-faa2-4ba2-a551q-1afdf565c889?alias=Life+is+too+short+for+no+alias&description=Every+alert+needs+a+description&actions=An+action&tags=["tag1","tag2"]&entity=An+example+entity&source=The+source&priority=P1&user=Dracula&note=Here+is+a+note
 
 Example using the command line:
 
-	shoutrrr send -u 'opsgenie://api.eu.opsgenie.com/token?tags=["tag1","tag2"]&description=testing&responders=[{"username":"superuser", "type": "user"}]&entity=Example Entity&source=Example Source&actions=["asdf", "bcde"]' -m "Hello World6"
+```shell
+shoutrrr send -u 'opsgenie://api.eu.opsgenie.com/token?tags=["tag1","tag2"]&description=testing&responders=[{"username":"superuser", "type": "user"}]&entity=Example Entity&source=Example Source&actions=["asdf", "bcde"]' -m "Hello World6"
+```
+
 
diff --git a/docs/services/pushbullet.md b/docs/services/pushbullet.md
@@ -1,4 +1,8 @@
 # Pushbullet
 
 ## URL Format
-*pushbullet://__`api-token`__[/__`device`__/#__`channel`__/__`email`__]*    
+
+!!! info ""
+    pushbullet://__`api-token`__[/__`device`__/#__`channel`__/__`email`__]
+
+--8<-- "docs/services/pushbullet/config.md"
diff --git a/docs/services/pushover.md b/docs/services/pushover.md
@@ -2,7 +2,10 @@
 
 ## URL Format
 
-*pushover://shoutrrr:__`apiToken`__@__`userKey`__/?devices=__`device1`__[,__`device2`__, ...]*
+!!! info ""
+    pushover://shoutrrr:__`apiToken`__@__`userKey`__/?devices=__`device1`__[,__`device2`__, ...]
+
+--8<-- "docs/services/pushover/config.md"
 
 ## Getting the keys from Pushover
 
@@ -23,6 +26,7 @@ The __`apiToken`__ is displayed at the top of the application page.
 You can optionally specify the __`title`__ and __`priority`__ parameters in the URL:  
 *pushover://shoutrrr:__`token`__@__`userKey`__/?devices=__`device`__&title=Custom+Title&priority=1*
 
-__Note:__ Only supply priority values between -1 and 1, since 2 requires additional parameters that are not supported yet.
+!!! note
+    Only supply priority values between -1 and 1, since 2 requires additional parameters that are not supported yet.
 
 Please refer to the [Pushover API documentation](https://pushover.net/api#messages) for more information.  
diff --git a/docs/services/rocketchat.md b/docs/services/rocketchat.md
@@ -1,8 +1,11 @@
 # Rocket.chat
 
 ## URL Format
-*rocketchat://[__`username`__@]__`rocketchat-host`__/__`token`__[/__`channel`&#124;`@recipient`__]* 
 
+!!! info ""
+    rocketchat://[__`username`__@]__`rocketchat-host`__/__`token`__[/__`channel`&#124;`@recipient`__]* 
+
+--8<-- "docs/services/rocketchat/config.md"
 
 ## Creating a Webhook in Rocket.chat
 

diff --git a/docs/services/slack.md b/docs/services/slack.md
@@ -1,4 +1,33 @@
 # Slack
 
+The slack notification service uses [Slack Webhook](https://api.slack.com/messaging/webhooks)s to send messages.  
+Follow the [Getting started with Incoming Webhooks](https://api.slack.com/messaging/webhooks#getting_started) guide and
+replace the initial `https://hooks.slack.com/services/` part of the webhook URL with `slack://` to get your Shoutrrr URL.
+
+*Slack Webhook URL:*
+
+!!! info ""
+    https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX
+
+Shoutrrr URL:
+
+!!! info ""
+    slack://T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX
+
+
 ## URL Format
-*slack://[__`botname`__@]__`token-a`__/__`token-b`__/__`token-c`__*      
+
+--8<-- "docs/services/slack/config.md"
+
+!!! info "Color format"
+    The format for the `Color` prop follows the [slack docs](https://api.slack.com/reference/messaging/attachments#fields)
+    but `#` needs to be escaped as `%23` when passed in a URL.  
+    So <span style="background:#ff8000;width:.9em;height:.9em;display:inline-block;vertical-align:middle"></span><code>#ff8000</code> would be `%23ff8000` etc.
+
+## Examples
+
+!!! example
+    All fields set:
+    ```uri
+    slack://ShoutrrrBot@T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX?color=good&title=Great+News
+    ```
diff --git a/docs/services/teams.md b/docs/services/teams.md
@@ -1,8 +1,18 @@
 # Teams
 
+!!! attention Webhook URL scheme changed
+    Microsoft has changed the URL scheme for Teams webhooks. You will now have to specify the hostname using:
+    ```text
+    ?host=example.webhook.office.com
+    ```
+    Where `example` is your organization short name
+
 ## URL Format
 
-*teams://__`token-a`__/__`token-b`__/__`token-c`__*
+!!! info ""
+    teams://__`group`__@__`tenant`__/__`altId`__/__`groupOwner`__?host=example.webhook.office.com
+
+--8<-- "docs/services/teams/config.md"
 
 ## Setting up a webhook
 

diff --git a/docs/services/telegram.md b/docs/services/telegram.md
@@ -2,7 +2,10 @@
 
 ## URL Format
 
-*telegram://__`token`__@telegram?channels=__`channel-1`__[,__`channel-2`__,...]*
+!!! info ""
+    telegram://__`token`__@telegram?channels=__`channel-1`__[,__`channel-2`__,...]
+
+--8<-- "docs/services/telegram/config.md"
 
 ## Getting a token for Telegram
 

diff --git a/docs/services/zulip.md b/docs/services/zulip.md
@@ -3,7 +3,15 @@
 ## URL Format
 
 The shoutrrr service URL should look like this:  
-> zulip://__`bot-mail`__:__`bot-key`__@__`zulip-domain`__/?stream=__`name-or-id`__&topic=__`name`__
+!!! info ""
+    zulip://__`bot-mail`__:__`bot-key`__@__`zulip-domain`__/?stream=__`name-or-id`__&topic=__`name`__
+
+--8<-- "docs/services/zulip/config.md"
+
+!!! note
+    Since __`bot-mail`__  is a mail address you need to URL escape the `@` in it to `%40`.
+
+### Examples
 
 Stream and topic are both optional and can be given as parameters to the Send method:
 
@@ -17,7 +25,5 @@ Stream and topic are both optional and can be given as parameters to the Send me
   sender.Send(message, &params)
 ```
 
-Since __`bot-mail`__  is a mail address you need to URL escape the `@` in it to `%40`.
-
-An example service URL would look like:
-> zulip://my-bot%40zulipchat.com:correcthorsebatterystable@example.zulipchat.com?stream=foo&topic=bar
+!!! example "Example service URL"
+    zulip://my-bot%40zulipchat.com:correcthorsebatterystable@example.zulipchat.com?stream=foo&topic=bar
diff --git a/generate-service-config-docs.sh b/generate-service-config-docs.sh
@@ -1,15 +1,27 @@
 #!/usr/bin/env bash
 
-for S in ./pkg/services/*; do
-  SERVICE=$(basename "$S")
-  if [[ "$SERVICE" == "standard" ]] || [[ -f "$S" ]]; then
-    continue
-  fi
+set -e
+
+function generate_docs() {
+  SERVICE=$1
   DOCSPATH=./docs/services/$SERVICE
   echo -en "Creating docs for \e[96m$SERVICE\e[0m... "
   mkdir -p "$DOCSPATH"
   go run ./cli docs -f markdown "$SERVICE" > "$DOCSPATH"/config.md
   if [ $? ]; then
     echo -e "Done!"
   fi
+}
+
+if [[ -n "$1" ]]; then
+  generate_docs "$1"
+  exit 0
+fi
+
+for S in ./pkg/services/*; do
+  SERVICE=$(basename "$S")
+  if [[ "$SERVICE" == "standard" ]] || [[ -f "$S" ]]; then
+    continue
+  fi
+  generate_docs "$SERVICE"
 done
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -14,8 +14,12 @@ markdown_extensions:
   - toc:
       permalink: True
       separator: '_'
+  - admonition
+  - pymdownx.details
   - pymdownx.highlight
+  - pymdownx.inlinehilite
   - pymdownx.superfences
+  - pymdownx.mark
   - pymdownx.snippets:
       check_paths: true
 nav: