docs: add pre-release banner (#90)

* docs: add pre-release banner

* add echo

Author: tlambert03

.github/workflows/deploy_docs.yml

@@ -33,12 +33,23 @@ jobs:
         if: ${{ startsWith(github.ref, 'refs/tags/') }}
         run: |
           VERSION=$(git describe --abbrev=0 --tags)
-          echo "Deploy release docs to version $VERSION"
-          mike deploy --push --update-aliases $VERSION latest
+          # check if rc or beta release
+          if [[ $VERSION == *"rc"* ]] || [[ $VERSION == *"beta"* ]]; then
+            export DOCS_PRERELEASE=true
+            echo "Deploying pre-release docs"
+            mike deploy --push --update-aliases $VERSION rc
+          else
+            echo "Deploying release docs"
+            mike deploy --push --update-aliases $VERSION latest
+          fi
+        env:
+          DOCS_DEV: false
 
       - name: Deploy dev docs
         if: ${{ !startsWith(github.ref, 'refs/tags/') }}
         run: mike deploy --push --update-aliases dev
+        env:
+          DOCS_DEV: true
 
       - name: Update default release docs
         run: mike set-default --push latest

docs/_overrides/main.html

@@ -1,5 +1,19 @@
 {% extends "base.html" %}
 
+{% set prebuild = 'pre-release' if config.extra.pre_release else 'dev' if config.extra.dev_build else '' %}
+
+{% block announce %}
+  {%- if prebuild -%} <!-- See the dashes here -->
+    <!-- Need to reapply margin from base CSS, which is overridden in extra CSS (to fix empty banner) -->
+    <div style="margin: 0.6rem auto">
+      You are currently viewing documentation for a <strong>{{prebuild}}</strong> build.
+      This may reference unreleased features.
+      For latest release, see
+      <strong><a href="{{ '../' ~ base_url }}">stable release docs</a></strong>.
+    </div>
+  {%- endif -%}
+{% endblock %}
+
 {% block outdated %}
   You're not viewing the latest version.
   <a href="{{ '../' ~ base_url }}">

mkdocs.yml

@@ -126,6 +126,10 @@ hooks:
 extra:
   version:
     provider: mike
+  # either of these tags will enable the "viewing pre" announcement banner
+  # see _overrides/main.html
+  pre_release: !ENV ["DOCS_PRERELEASE", false]
+  dev_build: !ENV ["DOCS_DEV", false]
   social:
     - icon: fontawesome/brands/github
       link: https://github.com/pyapp-kit