From 2fd024519096c5866c6d20a2fcde752e1dad4472 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 9 Feb 2026 17:45:10 +0000
Subject: [PATCH 1/2] Initial plan


From f844fc878e414aa00ee5b0557925de43537c769b Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 9 Feb 2026 17:47:07 +0000
Subject: [PATCH 2/2] Document sphinx-multiversion workflow requirements and
 add explanatory comments

Co-authored-by: digreatbrian <119015367+digreatbrian@users.noreply.github.com>
---
 .github/workflows/docs.yml |  7 +++++
 docs/README.md             | 57 ++++++++++++++++++++++++++++++++++++--
 docs/source/conf.py        |  3 ++
 3 files changed, 64 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 478044c..fd9e189 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -1,5 +1,10 @@
 name: Build & Deploy Sphinx Multiversion Docs
 
+# IMPORTANT: This workflow must trigger on BOTH branches AND tags
+# - Branch triggers (main): Updates docs for the latest development version
+# - Tag triggers (*): Builds docs when new versions are released  
+# - sphinx-multiversion uses git history to build docs for all versions together
+# - fetch-depth: 0 is required to access full git history for multiversion builds
 on:
   push:
     branches:
@@ -23,6 +28,8 @@ jobs:
 
     steps:
       # Checkout full history (required for sphinx-multiversion)
+      # fetch-depth: 0 ensures all branches and tags are available
+      # so sphinx-multiversion can build docs for all versions
       - name: Checkout repository
         uses: actions/checkout@v4
         with:
diff --git a/docs/README.md b/docs/README.md
index 42e913c..958296c 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,4 +1,55 @@
 # Directory for Duck framework Docs
-- These docs can only be build with `sphinx-multiversion`.
-- Workflow file is located at `.github/docs.yml`.
-- Docs source is at `docs/source`.
+
+This directory contains the documentation for the Duck framework, built using Sphinx with sphinx-multiversion for multi-version documentation support.
+
+## Overview
+
+- These docs are built with `sphinx-multiversion` to support documentation for multiple versions/tags
+- Workflow file is located at `.github/workflows/docs.yml`
+- Docs source is at `docs/source`
+- Configuration is in `docs/source/conf.py`
+
+## Sphinx Multiversion Setup
+
+### Why Both Branch and Tag Triggers?
+
+The GitHub Actions workflow **must trigger on BOTH the main branch AND tags** because:
+
+1. **Tag triggers (`tags: ['*']`)**: Required to build documentation when new version tags are created
+2. **Branch triggers (`branches: [main]`)**: Required to update documentation for the latest development version
+3. **sphinx-multiversion** scans the entire git history (all branches and tags) and builds documentation for each version in a single unified build
+
+### How It Works
+
+1. When the workflow triggers (on push to main or when a tag is pushed):
+   - Full git history is checked out (`fetch-depth: 0`)
+   - sphinx-multiversion scans all branches and tags
+   - Documentation is built for each version that matches the configured filters
+   - All versions are compiled into a single deployable documentation site
+
+2. Configuration in `docs/source/conf.py`:
+   ```python
+   smv_tag_whitelist = r'^.*$'  # Match all tags
+   smv_branch_whitelist = r'^(main|stable)$'  # Match main and stable branches
+   smv_remote_whitelist = r'^origin$'
+   ```
+
+### Building Locally
+
+To build the docs locally with multiversion support:
+
+```bash
+# Install dependencies
+pip install -r docs/requirements.txt
+pip install .
+
+# Build multiversion docs
+sphinx-multiversion docs/source docs/build/html
+```
+
+### Important Notes
+
+- **DO NOT remove either the tag or branch trigger** from the workflow - both are essential for sphinx-multiversion to work correctly
+- The `fetch-depth: 0` setting in the checkout action is critical - it ensures the full git history is available
+- Without full history, sphinx-multiversion cannot see all versions and will only build for the current commit
+
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 78bf451..bc4a55c 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -81,6 +81,9 @@ def read_metadata_from_init(init_path):
 
 
 # Sphinx multiversion configuration
+# Note: The GitHub Actions workflow must trigger on BOTH branches AND tags
+# for sphinx-multiversion to build docs for all versions correctly.
+# See docs/README.md and .github/workflows/docs.yml for details.
 smv_tag_whitelist = r'^.*$'  # Match all tags
 smv_branch_whitelist = r'^(main|stable)$'
 smv_remote_whitelist = r'^origin$'