docs: fix HexDocs source links; add a docs-only publish workflow

.github/workflows/docs.yml

@@ -0,0 +1,66 @@
+name: Docs
+
+# Actions → Docs → Run workflow, pick a package. Republishes its HexDocs from
+# main for the version in mix.exs (its latest release), for doc fixes between
+# releases. Releases publish docs on their own. Not run on every push: main
+# can document unreleased APIs, which would show up under the released
+# version.
+
+on:
+  workflow_dispatch:
+    inputs:
+      package:
+        description: Package
+        type: choice
+        options: [durable, durable_dashboard]
+
+env:
+  ELIXIR_VERSION: "1.20"
+  OTP_VERSION: "29"
+
+jobs:
+  docs:
+    name: Publish docs
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: ${{ inputs.package }}
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Elixir
+        uses: erlef/setup-beam@v1
+        with:
+          elixir-version: ${{ env.ELIXIR_VERSION }}
+          otp-version: ${{ env.OTP_VERSION }}
+
+      # Before the JS deps: assets/package.json links phoenix and LiveView
+      # from deps/.
+      - name: Install dependencies
+        run: mix deps.get
+
+      # The dashboard's hex.publish alias builds its assets first.
+      - name: Set up pnpm
+        if: inputs.package == 'durable_dashboard'
+        uses: pnpm/action-setup@v6
+        with:
+          version: 9
+
+      - name: Set up Node
+        if: inputs.package == 'durable_dashboard'
+        uses: actions/setup-node@v6
+        with:
+          node-version: "20"
+          cache: pnpm
+          cache-dependency-path: durable_dashboard/assets/pnpm-lock.yaml
+
+      - name: Install JS dependencies
+        if: inputs.package == 'durable_dashboard'
+        working-directory: durable_dashboard/assets
+        run: pnpm install --frozen-lockfile
+
+      - name: Publish docs to Hex
+        env:
+          HEX_API_KEY: ${{ secrets.HEX_API_KEY }}
+        run: mix hex.publish docs --yes

README.md

@@ -64,6 +64,10 @@ tag and skips whatever already went out. Release
 `durable` first when the dashboard needs its changes: the dashboard is
 published against durable from Hex.
 
+Releases publish their HexDocs too. To fix docs without a release, run
+**Actions → Docs**: it republishes a package's docs from `main` under its
+current version.
+
 Preview a changelog locally with
 `git cliff --include-path "durable/**" --tag-pattern "^durable-v" --unreleased`.
 

durable/mix.exs

@@ -92,7 +92,8 @@ defmodule Durable.MixProject do
     [
       main: "readme",
       source_url: @source_url,
-      source_ref: "durable-v#{@version}",
+      # Each package lives in a subdirectory and has its own tags.
+      source_url_pattern: "#{@source_url}/blob/durable-v#{@version}/durable/%{path}#L%{line}",
       extras: [
         "README.md",
         "CHANGELOG.md",

durable_dashboard/mix.exs

@@ -113,7 +113,9 @@ defmodule DurableDashboard.MixProject do
     [
       main: "readme",
       source_url: @source_url,
-      source_ref: "durable_dashboard-v#{@version}",
+      # Each package lives in a subdirectory and has its own tags.
+      source_url_pattern:
+        "#{@source_url}/blob/durable_dashboard-v#{@version}/durable_dashboard/%{path}#L%{line}",
       extras: ["README.md", "CHANGELOG.md"]
     ]
   end