docs: set up versioned documentation with mike

.github/workflows/publish-docs.yml

@@ -8,6 +8,20 @@ on:
       - '*'
   pull_request:
   workflow_dispatch:
+    inputs:
+      version:
+        description: 'Docs version to deploy (e.g. 0.1.3)'
+        required: true
+        type: string
+      aliases:
+        description: 'Optional space-separated aliases (e.g. "latest" or "latest dev")'
+        required: false
+        type: string
+      delete_old_versions:
+        description: 'Delete old docs versions after deployment'
+        required: true
+        default: true
+        type: boolean
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
@@ -19,35 +33,76 @@ permissions:
   id-token: write
 
 jobs:
-  deploy_docs:
+  build_docs:
     if: github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/') || github.event_name == 'workflow_dispatch'
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/configure-pages@v6
-
       - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
 
       - name: Setup Python
         uses: actions/setup-python@v6
         with:
           python-version: 3.x
 
       - name: Install dependencies
-        run: pip install zensical==0.0.50
+        run: pip install zensical==0.0.50 git+https://github.com/squidfunk/mike.git
+
+      - name: Setup Java
+        uses: actions/setup-java@v4
+        with:
+          distribution: 'zulu'
+          java-version: '21'
+
+      - name: Get VERSION_NAME
+        id: version_name
+        run: echo "VERSION_NAME=$(grep '^VERSION_NAME=' gradle.properties | cut -d'=' -f2)" >> $GITHUB_OUTPUT
+
+      - name: Resolve docs deployment
+        id: docs
+        env:
+          VERSION_NAME: ${{ steps.version_name.outputs.VERSION_NAME }}
+        run: |
+          if [ "$GITHUB_EVENT_NAME" = "workflow_dispatch" ]; then
+            docs_version="${{ inputs.version }}"
+            docs_aliases="${{ inputs.aliases }}"
+          elif echo "$VERSION_NAME" | grep -q "SNAPSHOT"; then
+            docs_version="dev"
+            docs_aliases=""
+          else
+            docs_version="$VERSION_NAME"
+            docs_aliases="latest"
+          fi
+          echo "version=$docs_version" >> $GITHUB_OUTPUT
+          echo "aliases=$docs_aliases" >> $GITHUB_OUTPUT
+          echo "Resolved: version=$docs_version aliases=$docs_aliases"
+
+      - name: Configure git for mike
+        run: |
+          git config --local user.email "github-actions[bot]@users.noreply.github.com"
+          git config --local user.name "github-actions[bot]"
+          git fetch origin gh-pages --depth=1 || true
 
       - name: Build docs
-        run: ./scripts/build_docs.sh build
+        env:
+          DEVVIEW_VERSION: ${{ steps.docs.outputs.version }}
+        run: ./scripts/build_docs.sh --prep-only
 
-      - name: Upload docs
-        uses: actions/upload-pages-artifact@v5
-        with:
-          path: site
+      - name: Deploy docs with mike
+        if: github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/') || github.event_name == 'workflow_dispatch'
+        env:
+          DOCS_VERSION: ${{ steps.docs.outputs.version }}
+          DOCS_ALIASES: ${{ steps.docs.outputs.aliases }}
+        run: mike deploy -u --push $DOCS_VERSION $DOCS_ALIASES
+
+      - name: Set default version
+        if: (startsWith(github.ref, 'refs/tags/') || github.event_name == 'workflow_dispatch') && steps.docs.outputs.aliases != ''
+        run: mike set-default --push latest
 
-      - name: Deploy docs
-        uses: actions/deploy-pages@v5
-        id: deployment
+      - name: Delete old doc versions
+        if: (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/') || github.event_name == 'workflow_dispatch') && (github.event_name != 'workflow_dispatch' || inputs.delete_old_versions)
+        run: |
+          git fetch origin gh-pages --depth=1
+          ./scripts/delete_old_version_docs.sh

docs/index.md

@@ -24,11 +24,11 @@
 
 ## What's New
 
-### v0.1.2 - Patch Updates
+### v0.1.3 - NetworkMock and navigation fixes
 
-- Fixed Android packaging excludes to preserve Kotlin module metadata in published artifacts
-- Updated sample app feature setup with local and remote feature examples
-- Improved docs formatting so lists render correctly on Home and License pages
+- Added `NetworkMockResourceLoader` fun interface in `devview-networkmock-core` for easier DI framework integration (Koin, Hilt, etc.)
+- Fixed DevView overlay back navigation: the overlay's back handler now correctly yields priority to the host app when closed
+- Fixed crash on Network Mock screen startup caused by `MissingResourceException` when probing absent response files
 
 ---
 

scripts/build_docs.sh

@@ -8,7 +8,9 @@ cp -r internal/dokka/build/dokka/html/ docs/api/
 
 cp CHANGELOG.md docs/changelog.md
 
-DEVVIEW_VERSION=$(grep "^VERSION_NAME=" gradle.properties | cut -d'=' -f2 | sed 's/-SNAPSHOT//')
+DEVVIEW_VERSION=${DEVVIEW_VERSION:-$(grep "^VERSION_NAME=" gradle.properties | cut -d'=' -f2 | sed 's/-SNAPSHOT//')}
 find docs -name "*.md" -exec sed -i "s/DEVVIEW_VERSION/$DEVVIEW_VERSION/g" {} \;
 
-zensical $@ --clean
+if [ "$1" != "--prep-only" ]; then
+    zensical $@ --clean
+fi

scripts/release.py

@@ -41,6 +41,38 @@ def find_published_api_files() -> list[Path]:
     return sorted(api_files)
 
 
+def extract_changelog_section(version: str, changelog: Path) -> str:
+    content = changelog.read_text(encoding="utf-8")
+    start = content.find(f"## [{version}]")
+    if start == -1:
+        return ""
+    next_section = content.find("\n## [", start + 1)
+    section = content[start:next_section].strip() if next_section != -1 else content[start:].strip()
+    # Drop the "## [version] - date" header line
+    lines = section.splitlines()[1:]
+    return "\n".join(lines).strip()
+
+
+def update_whats_new(version: str, changelog_section: str, index: Path) -> None:
+    content = index.read_text(encoding="utf-8")
+    start = content.find("## What's New\n")
+    if start == -1:
+        return
+    end = content.find("\n---\n", start)
+    if end == -1:
+        return
+    # Convert ### Added/Fixed/Changed sub-headers into bullet groups
+    lines = []
+    for line in changelog_section.splitlines():
+        if line.startswith("### "):
+            lines.append(f"\n**{line[4:]}**")
+        elif line.startswith("- "):
+            lines.append(line)
+    new_section = f"## What's New\n\n### v{version}\n\n" + "\n".join(lines).strip()
+    content = content[:start] + new_section + content[end:]
+    index.write_text(content, encoding="utf-8")
+
+
 def update_changelog(version: str, changelog: Path) -> None:
     content = changelog.read_text()
     today = date.today().strftime("%Y-%m-%d")
@@ -125,9 +157,20 @@ def main():
     print("\nStep 3: Updating CHANGELOG.md...")
     update_changelog(new_version, changelog)
 
+    # Step 3b: Sync docs changelog and update What's New
+    print("\nStep 3b: Updating docs/changelog.md and docs/index.md...")
+    docs_changelog = Path("docs/changelog.md")
+    docs_index = Path("docs/index.md")
+    shutil.copy2(changelog, docs_changelog)
+    section = extract_changelog_section(new_version, changelog)
+    if section:
+        update_whats_new(new_version, section, docs_index)
+    else:
+        print("  Warning: Could not find changelog section for this version")
+
     # Step 4: Commit and tag
     print("\nStep 4: Committing and tagging...")
-    run(["git", "add", str(gradle_props), str(changelog)])
+    run(["git", "add", str(gradle_props), str(changelog), str(docs_index)])
     for api_txt in api_files:
         version_txt = api_txt.parent / f"{new_version}.txt"
         run(["git", "add", str(version_txt)])

zensical.toml

@@ -379,6 +379,10 @@ logo = "assets/branding/devview-icon-dark.svg"
 icon = "fontawesome/brands/github"
 link = "https://github.com/worldline"
 
+[project.extra.version]
+provider = "mike"
+alias = true
+
 [project.markdown_extensions.codehilite]
 [project.markdown_extensions.pymdownx.betterem]
 [project.markdown_extensions.pymdownx.tilde]