docs: add multi-version support (#178)

* docs: add mike support * docs: update dev docs * ci: build and deploy mike docs * fix secret variable
containrrr · Jul 3, 2021 · a86ddc7 · a86ddc7
1 parent 1e34cb3
commit a86ddc7
Show file tree

Hide file tree

Showing 8 changed files with 55 additions and 22 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -3,8 +3,12 @@ name: Deploy Docs
 on:
   workflow_dispatch:
   workflow_run:
-    workflows: ["Release Workflow"]
-    types: [completed]
+    workflows: [ "Release Workflow" ]
+    types: [ completed ]
+  push:
+    branches:
+      - main
+      - latest
 
 jobs:
   build:
@@ -20,20 +24,29 @@ jobs:
           python-version: '3.x'
 
       - name: Install mkdocs
+        env:
+          MKDOCSMAT_TOKEN: ${{ secrets.MKDOCSMAT_TOKEN }}
         run: |
           pip install \
             mkdocs \
-            mkdocs-material \
-            md-toc
+            mike \
+            md-toc \
+            git+https://[email protected]/squidfunk/mkdocs-material-insiders.git
 
       - name: Generate service config docs
         run: bash generate-service-config-docs.sh
 
-      - name: Generate docs
-        run: mkdocs build
+      - name: Update env for docs (dev/main)
+        if: ${{ github.ref == 'refs/heads/main' }}
+        run: |
+          echo "DOCS_EDIT_URI=/edit/main/docs/" >> $GITHUB_ENV
+          echo "DOCS_VERSION=dev" >> $GITHUB_ENV
 
-      - name: Publish docs
-        uses: peaceiris/actions-gh-pages@v3
-        with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./site
+      - name: Update env (latest)
+        if: ${{ github.ref == 'refs/heads/latest' }}
+        run: |
+          echo "DOCS_EDIT_URI=/edit/latest/docs/" >> $GITHUB_ENV
+          echo "DOCS_VERSION=latest" >> $GITHUB_ENV
+
+      - name: Deploy docs
+        run: mike deploy --push $DOCS_VERSION
diff --git a/docs/overrides/main.html b/docs/overrides/main.html
@@ -0,0 +1,9 @@
+{% extends "base.html" %}
+
+{% block outdated %}
+You're not viewing the latest version.
+<a href="{{ '../' ~ base_url }}">
+
+    <strong>Click here to go to latest.</strong>
+</a>
+{% endblock %}
diff --git a/docs/services/generic.md b/docs/services/generic.md
@@ -0,0 +1,5 @@
+# Generic
+
+## URL Format
+
+--8<-- "docs/services/generic/config.md"
diff --git a/docs/services/googlechat.md b/docs/services/googlechat.md
@@ -28,7 +28,7 @@ room menu.
 ![Screenshot 2](googlechat/hangouts-2.png)
 
 3. Name the webhook and save.
-![Screenshot 3](googkechat/hangouts-3.png)
+![Screenshot 3](googlechat/hangouts-3.png)
 
 4. Copy the URL.
 ![Screenshot 4](googlechat/hangouts-4.png)

diff --git a/docs/services/hangouts.md b/docs/services/hangouts.md
@@ -1,7 +1,7 @@
 # Hangouts Chat
 
 Google Chat was previously known as *Hangouts Chat*. See [Google
-Chat](../googlechat.md).
+Chat](googlechat.md).
 
 Using `hangouts` in the service URL instead `googlechat` is still
 supported, although deprecated.
diff --git a/docs/services/logger.md b/docs/services/logger.md
@@ -0,0 +1,6 @@
+# Logger
+
+No configuration options are available for this service.
+
+It simply emits notifications to the Shoutrrr log which is
+configured by the consumer.
diff --git a/docs/services/overview.md b/docs/services/overview.md
@@ -7,10 +7,11 @@ Click on the service for a more thorough explanation. <!-- @formatter:off -->
 | [Discord](./discord.md)           | *discord://__`token`__@__`id`__*                                                                                                                |
 | [Email](./email.md)               | *smtp://__`username`__:__`password`__@__`host`__:__`port`__/?fromAddress=__`fromAddress`__&toAddresses=__`recipient1`__[,__`recipient2`__,...]* |
 | [Gotify](./gotify.md)             | *gotify://__`gotify-host`__/__`token`__*                                                                                                        |
-| [Google Chat](./googlechat.md)    | *googlechat://chat.googleapis.com/v1/spaces/FOO/messages?key=bar&token=baz*                                                                       |
+| [Google Chat](./googlechat.md)    | *googlechat://chat.googleapis.com/v1/spaces/FOO/messages?key=bar&token=baz*                                                                     |
 | [IFTTT](./ifttt.md)               | *ifttt://__`key`__/?events=__`event1`__[,__`event2`__,...]&value1=__`value1`__&value2=__`value2`__&value3=__`value3`__*                         |
 | [Join](./join.md)                 | *join://shoutrrr:__`api-key`__@join/?devices=__`device1`__[,__`device2`__, ...][&icon=__`icon`__][&title=__`title`__]*                          |
 | [Mattermost](./mattermost.md)     | *mattermost://[__`username`__@]__`mattermost-host`__/__`token`__[/__`channel`__]*                                                               |
+| [Matrix](./matrix.md)             | *matrix://__`username`__:__`password`__@__`host`__:__`port`__/[?rooms=__`!roomID1`__[,__`roomAlias2`__]]*                                       |
 | [OpsGenie](./opsgenie.md)         | *opsgenie://__`host`__/token?responders=__`responder1`__[,__`responder2`__]*                                                                    |
 | [Pushbullet](./pushbullet.md)     | *pushbullet://__`api-token`__[/__`device`__/#__`channel`__/__`email`__]*                                                                        |
 | [Pushover](./pushover.md)         | *pushover://shoutrrr:__`apiToken`__@__`userKey`__/?devices=__`device1`__[,__`device2`__, ...]*                                                  |
@@ -25,12 +26,5 @@ Click on the service for a more thorough explanation. <!-- @formatter:off -->
 | Service                           | Description                                                                                                                                     |
 | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
 | [Logger](./logger.md)             | Writes notification to a configured go `log.Logger`                                                                                             |
-
-## Upcoming services
-
-*Note that these are not available in the current release*
-
-| Service                           | Description                                                                                                                                     |
-| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
 | [Generic Webhook](./generic.md)   | Sends notifications directly to a webhook                                                                                                       |
-| [Matrix](./matrix.md)             | *matrix://__`username`__:__`password`__@__`host`__:__`port`__/[?rooms=__`!roomID1`__[,__`roomAlias2`__]]*                                       |
+
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -8,6 +8,11 @@ theme:
     scheme: shoutrrr
   logo: shoutrrr-180px.png
   favicon: favicon.ico
+  custom_dir: docs/overrides
+extra:
+  version:
+    provider: mike
+  generator: false
 extra_css:
   - stylesheets/theme.css
 markdown_extensions:
@@ -34,6 +39,7 @@ nav:
       - IFTTT: 'services/ifttt.md'
       - Join: 'services/join.md'
       - Mattermost: 'services/mattermost.md'
+      - Matrix: 'services/matrix.md'
       - OpsGenie: 'services/opsgenie.md'
       - Pushbullet: 'services/pushbullet.md'
       - Pushover: 'services/pushover.md'