Workflow tweaks for dev and stable docs

.github/workflows/docs-dev.yml

@@ -26,10 +26,13 @@ jobs:
         # First configure git correctly
         # Then use the alias of the current dev version to delete it based on its identifier
         # Then deploy the new version so that there is only one dev version at a time
+        # Only make dev the default if no stable version exists yet, so stable stays the default once published
         run: |
           git config user.name github-actions
           git config user.email [email protected]
           git fetch origin gh-pages --depth=1
           mike delete --push $(mike list | grep dev | awk '{print $1}' | tr -d '()')
           mike deploy --push --update-aliases "${{ env.package_version }}-dev" dev
-          mike set-default --push --allow-empty dev
+          if ! mike list stable > /dev/null 2>&1; then
+            mike set-default --push dev
+          fi

.github/workflows/docs-stable.yml

@@ -2,9 +2,12 @@ name: Publish Stable Docs
 
 on:
   workflow_dispatch:
+  release:
+    types: [published]
 
 jobs:
   publish:
+    if: github.event_name == 'workflow_dispatch' || !github.event.release.prerelease
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
@@ -20,6 +23,9 @@ jobs:
           python -c 'import pathpyG; print(f"package_version={pathpyG.__version__}")' >> "$GITHUB_ENV"
 
       - name: Publish docs
+        env:
+          # Pin "Open in Colab" links to the commit these docs are built from	
+          DOCS_GIT_REF: ${{ github.sha }}
         run: |
           git config user.name github-actions
           git config user.email [email protected]

docs/getting_started.md

@@ -30,9 +30,6 @@ uv pip install pathpyg[cu129]
 
 You can install the latest stable release of PathpyG via pip:
 
-!!! warning "TODO"
-    This is not yet available. We will release the first stable version soon.
-
 ```bash
 pip install pathpyg
 ```

docs/overrides/home.html

@@ -1,4 +1,4 @@
-{% extends "base.html" %}
+{% extends "main.html" %}
 
 {% block tabs %}
 <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/OwlCarousel2/2.3.4/assets/owl.carousel.min.css">

docs/overrides/main.html

@@ -1,21 +1,26 @@
 {% extends "base.html" %}
 
 <!-- You can include an announcement bar with the block "announce" -->
+{% block announce -%}
+  {%- if config.extra.docs_version.endswith("-dev") %}
+    You're viewing the development docs. Features documented here may not be in a released version of pathpyG yet.
+  {%- endif %}
+{%- endblock %}
 
 <!-- Includes a download button in the Jupyter tutorials -->
 {% block content %}
 {% if page.nb_url %}
     <a href="{{ page.nb_url }}" title="Download Notebook" class="md-content__button md-icon">
         {% include ".icons/material/download.svg" %}
     </a>
-    <a href="{{ page.edit_url | replace('https://github.com/pathpy/pathpyG/edit/', 'https://colab.research.google.com/github/pathpy/pathpyG/blob/') }}" title="Open in Google Colab" class="md-content__button md-icon">
+    <a href="https://colab.research.google.com/github/pathpy/pathpyG/blob/{{ config.extra.git_ref }}/docs/{{ page.file.src_uri }}" title="Open in Google Colab" class="md-content__button md-icon">
       {% include ".icons/simple/googlecolab.svg" %}
     </a>
 {% endif %}
 {{ super() }}
 {% endblock %}
 
-<!-- Adds a warning to the top of the page if the page is not the dev or the stable version -->
+<!-- Adds a warning to the top of the page if the page is not the stable version -->
 {% block outdated %}
   You're not viewing the latest version.
   <a href="{{ '../' ~ base_url }}">

mkdocs.yml

@@ -79,8 +79,13 @@ plugins:
 
 extra:
   version:
-    default: dev
+    # Only the stable version hides the "not the latest version" banner
+    default: stable
     provider: mike
+  # Version being built by mike (e.g. "0.2.0-dev"); empty for plain mkdocs builds
+  docs_version: !ENV [MIKE_DOCS_VERSION, ""]
+  # Git ref for "Open in Colab" links; set to the build commit for stable docs
+  git_ref: !ENV [DOCS_GIT_REF, main]
 
 extra_css:
   - overrides/assets/stylesheets/header.css  # Remove the sitename from the header, since the logo already contains it