From 0fde20d3b5be3112b65bab9ee557bd66180e758f Mon Sep 17 00:00:00 2001
From: anakin87 <stefanofiorucci@gmail.com>
Date: Wed, 22 Oct 2025 16:42:24 +0200
Subject: [PATCH 01/14] docusaurus configs

---
 docs/pydoc/config_docusaurus/agents_api.yml   | 35 +++++++++++++++++++
 .../chat_message_stores_api.yml               | 28 +++++++++++++++
 .../config_docusaurus/generators_api.yml      | 28 +++++++++++++++
 .../config_docusaurus/preprocessors_api.yml   | 28 +++++++++++++++
 docs/pydoc/config_docusaurus/query_api.yml    | 28 +++++++++++++++
 .../config_docusaurus/retrievers_api.yml      | 31 ++++++++++++++++
 .../config_docusaurus/summarizers_api.yml     | 28 +++++++++++++++
 .../config_docusaurus/supercomponents_api.yml | 28 +++++++++++++++
 docs/pydoc/config_docusaurus/writers_api.yml  | 28 +++++++++++++++
 9 files changed, 262 insertions(+)
 create mode 100644 docs/pydoc/config_docusaurus/agents_api.yml
 create mode 100644 docs/pydoc/config_docusaurus/chat_message_stores_api.yml
 create mode 100644 docs/pydoc/config_docusaurus/generators_api.yml
 create mode 100644 docs/pydoc/config_docusaurus/preprocessors_api.yml
 create mode 100644 docs/pydoc/config_docusaurus/query_api.yml
 create mode 100644 docs/pydoc/config_docusaurus/retrievers_api.yml
 create mode 100644 docs/pydoc/config_docusaurus/summarizers_api.yml
 create mode 100644 docs/pydoc/config_docusaurus/supercomponents_api.yml
 create mode 100644 docs/pydoc/config_docusaurus/writers_api.yml

diff --git a/docs/pydoc/config_docusaurus/agents_api.yml b/docs/pydoc/config_docusaurus/agents_api.yml
new file mode 100644
index 00000000..1dfc5661
--- /dev/null
+++ b/docs/pydoc/config_docusaurus/agents_api.yml
@@ -0,0 +1,35 @@
+loaders:
+- ignore_when_discovered:
+  - __init__
+  modules:
+  - haystack_experimental.components.agents.agent
+  - haystack_experimental.components.agents.human_in_the_loop.breakpoint
+  - haystack_experimental.components.agents.human_in_the_loop.dataclasses
+  - haystack_experimental.components.agents.human_in_the_loop.errors
+  - haystack_experimental.components.agents.human_in_the_loop.policies
+  - haystack_experimental.components.agents.human_in_the_loop.strategies
+  - haystack_experimental.components.agents.human_in_the_loop.types
+  - haystack_experimental.components.agents.human_in_the_loop.user_interfaces
+  search_path:
+  - ../../../
+  type: haystack_pydoc_tools.loaders.CustomPythonLoader
+processors:
+- do_not_filter_modules: false
+  documented_only: true
+  expression: null
+  skip_empty_modules: true
+  type: filter
+- type: smart
+- type: crossref
+renderer:
+  description: Tool-using agents with provider-agnostic chat model support.
+  id: experimental-agents-api
+  markdown:
+    add_member_class_prefix: false
+    add_method_class_prefix: true
+    classdef_code_block: false
+    descriptive_class_title: false
+    descriptive_module_title: true
+    filename: experimental_agents_api.md
+  title: Agents
+  type: haystack_pydoc_tools.renderers.DocusaurusRenderer
diff --git a/docs/pydoc/config_docusaurus/chat_message_stores_api.yml b/docs/pydoc/config_docusaurus/chat_message_stores_api.yml
new file mode 100644
index 00000000..007a5bc8
--- /dev/null
+++ b/docs/pydoc/config_docusaurus/chat_message_stores_api.yml
@@ -0,0 +1,28 @@
+loaders:
+- ignore_when_discovered:
+  - __init__
+  modules:
+  - haystack_experimental.chat_message_stores.in_memory
+  search_path:
+  - ../../../
+  type: haystack_pydoc_tools.loaders.CustomPythonLoader
+processors:
+- do_not_filter_modules: false
+  documented_only: true
+  expression: null
+  skip_empty_modules: true
+  type: filter
+- type: smart
+- type: crossref
+renderer:
+  description: Storage for the chat messages.
+  id: experimental-chatmessage-store-api
+  markdown:
+    add_member_class_prefix: false
+    add_method_class_prefix: true
+    classdef_code_block: false
+    descriptive_class_title: false
+    descriptive_module_title: true
+    filename: experimental_chatmessage_store_api.md
+  title: ChatMessage Store
+  type: haystack_pydoc_tools.renderers.DocusaurusRenderer
diff --git a/docs/pydoc/config_docusaurus/generators_api.yml b/docs/pydoc/config_docusaurus/generators_api.yml
new file mode 100644
index 00000000..98f32ce6
--- /dev/null
+++ b/docs/pydoc/config_docusaurus/generators_api.yml
@@ -0,0 +1,28 @@
+loaders:
+- ignore_when_discovered:
+  - __init__
+  modules:
+  - haystack_experimental.components.generators.chat.openai
+  search_path:
+  - ../../../
+  type: haystack_pydoc_tools.loaders.CustomPythonLoader
+processors:
+- do_not_filter_modules: false
+  documented_only: true
+  expression: null
+  skip_empty_modules: true
+  type: filter
+- type: smart
+- type: crossref
+renderer:
+  description: Enables text generation using LLMs.
+  id: experimental-generators-api
+  markdown:
+    add_member_class_prefix: false
+    add_method_class_prefix: true
+    classdef_code_block: false
+    descriptive_class_title: false
+    descriptive_module_title: true
+    filename: experimental_generators_api.md
+  title: Generators
+  type: haystack_pydoc_tools.renderers.DocusaurusRenderer
diff --git a/docs/pydoc/config_docusaurus/preprocessors_api.yml b/docs/pydoc/config_docusaurus/preprocessors_api.yml
new file mode 100644
index 00000000..e20882cd
--- /dev/null
+++ b/docs/pydoc/config_docusaurus/preprocessors_api.yml
@@ -0,0 +1,28 @@
+loaders:
+- ignore_when_discovered:
+  - __init__
+  modules:
+  - haystack_experimental.components.preprocessors.embedding_based_document_splitter
+  search_path:
+  - ../../../
+  type: haystack_pydoc_tools.loaders.CustomPythonLoader
+processors:
+- do_not_filter_modules: false
+  documented_only: true
+  expression: null
+  skip_empty_modules: true
+  type: filter
+- type: smart
+- type: crossref
+renderer:
+  description: Pipelines wrapped as components.
+  id: experimental-preprocessors-api
+  markdown:
+    add_member_class_prefix: false
+    add_method_class_prefix: true
+    classdef_code_block: false
+    descriptive_class_title: false
+    descriptive_module_title: true
+    filename: experimental_preprocessors_api.md
+  title: Preprocessors
+  type: haystack_pydoc_tools.renderers.DocusaurusRenderer
diff --git a/docs/pydoc/config_docusaurus/query_api.yml b/docs/pydoc/config_docusaurus/query_api.yml
new file mode 100644
index 00000000..97c70710
--- /dev/null
+++ b/docs/pydoc/config_docusaurus/query_api.yml
@@ -0,0 +1,28 @@
+loaders:
+- ignore_when_discovered:
+  - __init__
+  modules:
+  - haystack_experimental.components.query.query_expander
+  search_path:
+  - ../../../
+  type: haystack_pydoc_tools.loaders.CustomPythonLoader
+processors:
+- do_not_filter_modules: false
+  documented_only: true
+  expression: null
+  skip_empty_modules: true
+  type: filter
+- type: smart
+- type: crossref
+renderer:
+  description: Components for query processing and expansion.
+  id: experimental-query-api
+  markdown:
+    add_member_class_prefix: false
+    add_method_class_prefix: true
+    classdef_code_block: false
+    descriptive_class_title: false
+    descriptive_module_title: true
+    filename: experimental_query_api.md
+  title: Query
+  type: haystack_pydoc_tools.renderers.DocusaurusRenderer
diff --git a/docs/pydoc/config_docusaurus/retrievers_api.yml b/docs/pydoc/config_docusaurus/retrievers_api.yml
new file mode 100644
index 00000000..db5e0ed5
--- /dev/null
+++ b/docs/pydoc/config_docusaurus/retrievers_api.yml
@@ -0,0 +1,31 @@
+loaders:
+- ignore_when_discovered:
+  - __init__
+  modules:
+  - haystack_experimental.components.retrievers.chat_message_retriever
+  - haystack_experimental.components.retrievers.multi_query_embedding_retriever
+  - haystack_experimental.components.retrievers.multi_query_text_retriever
+  search_path:
+  - ../../../
+  type: haystack_pydoc_tools.loaders.CustomPythonLoader
+processors:
+- do_not_filter_modules: false
+  documented_only: true
+  expression: null
+  skip_empty_modules: true
+  type: filter
+- type: smart
+- type: crossref
+renderer:
+  description: Sweep through Document Stores and return a set of candidate documents
+    that are relevant to the query.
+  id: experimental-retrievers-api
+  markdown:
+    add_member_class_prefix: false
+    add_method_class_prefix: true
+    classdef_code_block: false
+    descriptive_class_title: false
+    descriptive_module_title: true
+    filename: experimental_retrievers_api.md
+  title: Retrievers
+  type: haystack_pydoc_tools.renderers.DocusaurusRenderer
diff --git a/docs/pydoc/config_docusaurus/summarizers_api.yml b/docs/pydoc/config_docusaurus/summarizers_api.yml
new file mode 100644
index 00000000..61662cc8
--- /dev/null
+++ b/docs/pydoc/config_docusaurus/summarizers_api.yml
@@ -0,0 +1,28 @@
+loaders:
+- ignore_when_discovered:
+  - __init__
+  modules:
+  - haystack_experimental.components.summarizers.llm_summarizer
+  search_path:
+  - ../../../
+  type: haystack_pydoc_tools.loaders.CustomPythonLoader
+processors:
+- do_not_filter_modules: false
+  documented_only: true
+  expression: null
+  skip_empty_modules: true
+  type: filter
+- type: smart
+- type: crossref
+renderer:
+  description: Components that summarize texts into concise versions.
+  id: experimental-summarizers-api
+  markdown:
+    add_member_class_prefix: false
+    add_method_class_prefix: true
+    classdef_code_block: false
+    descriptive_class_title: false
+    descriptive_module_title: true
+    filename: experimental_summarizer_api.md
+  title: Summarizers
+  type: haystack_pydoc_tools.renderers.DocusaurusRenderer
diff --git a/docs/pydoc/config_docusaurus/supercomponents_api.yml b/docs/pydoc/config_docusaurus/supercomponents_api.yml
new file mode 100644
index 00000000..6b451dfb
--- /dev/null
+++ b/docs/pydoc/config_docusaurus/supercomponents_api.yml
@@ -0,0 +1,28 @@
+loaders:
+- ignore_when_discovered:
+  - __init__
+  modules:
+  - haystack_experimental.super_components.indexers.sentence_transformers_document_indexer
+  search_path:
+  - ../../../
+  type: haystack_pydoc_tools.loaders.CustomPythonLoader
+processors:
+- do_not_filter_modules: false
+  documented_only: true
+  expression: null
+  skip_empty_modules: true
+  type: filter
+- type: smart
+- type: crossref
+renderer:
+  description: Pipelines wrapped as components.
+  id: experimental-supercomponents-api
+  markdown:
+    add_member_class_prefix: false
+    add_method_class_prefix: true
+    classdef_code_block: false
+    descriptive_class_title: false
+    descriptive_module_title: true
+    filename: experimental_supercomponents_api.md
+  title: SuperComponents
+  type: haystack_pydoc_tools.renderers.DocusaurusRenderer
diff --git a/docs/pydoc/config_docusaurus/writers_api.yml b/docs/pydoc/config_docusaurus/writers_api.yml
new file mode 100644
index 00000000..e615d77a
--- /dev/null
+++ b/docs/pydoc/config_docusaurus/writers_api.yml
@@ -0,0 +1,28 @@
+loaders:
+- ignore_when_discovered:
+  - __init__
+  modules:
+  - haystack_experimental.components.writers.chat_message_writer
+  search_path:
+  - ../../../
+  type: haystack_pydoc_tools.loaders.CustomPythonLoader
+processors:
+- do_not_filter_modules: false
+  documented_only: true
+  expression: null
+  skip_empty_modules: true
+  type: filter
+- type: smart
+- type: crossref
+renderer:
+  description: Writers for Haystack.
+  id: experimental-writers-api
+  markdown:
+    add_member_class_prefix: false
+    add_method_class_prefix: true
+    classdef_code_block: false
+    descriptive_class_title: false
+    descriptive_module_title: true
+    filename: experimental_writers_api.md
+  title: Writers
+  type: haystack_pydoc_tools.renderers.DocusaurusRenderer

From ef748870c5cee2e5743541bf29eddc818b7ebbc2 Mon Sep 17 00:00:00 2001
From: anakin87 <stefanofiorucci@gmail.com>
Date: Wed, 22 Oct 2025 16:56:26 +0200
Subject: [PATCH 02/14] wip

---
 .github/utils/pydoc-markdown.sh       | 16 ++++++++-
 .github/workflows/docusaurus_sync.yml | 52 +++++++++++++++++++++++++++
 2 files changed, 67 insertions(+), 1 deletion(-)
 create mode 100644 .github/workflows/docusaurus_sync.yml

diff --git a/.github/utils/pydoc-markdown.sh b/.github/utils/pydoc-markdown.sh
index 670bd096..0344db5b 100755
--- a/.github/utils/pydoc-markdown.sh
+++ b/.github/utils/pydoc-markdown.sh
@@ -1,10 +1,24 @@
 #!/bin/bash
 
+# Usage: ./pydoc-markdown.sh [CONFIG_PATH]
+#
+# Generate documentation from pydoc-markdown config files.
+#
+# Examples:
+#   ./pydoc-markdown.sh                    # Uses default path: ../config/*
+#   ./pydoc-markdown.sh ../config/api/*    # Uses custom path
+#   ./pydoc-markdown.sh /path/to/configs/* # Uses absolute path
+
 set -e   # Fails on any error in the following loop
+
+# Set default config path or use provided parameter
+CONFIG_PATH="${1:-../config/*}"
+
 cd docs/pydoc
 rm -rf temp && mkdir temp
 cd temp
-for file in ../config/* ; do
+echo "Processing config files in $CONFIG_PATH"
+for file in $CONFIG_PATH ; do
     echo "Converting $file..."
     pydoc-markdown "$file"
 done
diff --git a/.github/workflows/docusaurus_sync.yml b/.github/workflows/docusaurus_sync.yml
new file mode 100644
index 00000000..bf40f7fc
--- /dev/null
+++ b/.github/workflows/docusaurus_sync.yml
@@ -0,0 +1,52 @@
+name: Sync API reference with Docusaurus
+
+on:
+  push:
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+*"
+
+  workflow_dispatch: # Activate this workflow manually
+    inputs:
+      tag:
+        description: "Tag with this format: v1.0.0. When running this workflow manually, version is irrelevant so you can use any value."
+        required: true
+        type: string
+        default: v1.0.0
+
+env:
+  # TAG: ${{ inputs.tag || github.ref_name }}
+
+  # for testing purposes
+  TAG: v1.0.0
+
+jobs:
+  generate-api-reference:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout this repo
+        uses: actions/checkout@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.10"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -U haystack-pydoc-tools
+
+      - name: Generate API reference
+        working-directory: ${{ steps.pathfinder.outputs.project_path }}
+
+        run: pydoc-markdown pydoc/config_docusaurus.yml
+
+      - name: Upload API reference artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ steps.pathfinder.outputs.integration_name }}
+          path: ${{ steps.pathfinder.outputs.project_path }}/${{ steps.pathfinder.outputs.integration_name }}.md
+          if-no-files-found: error
+          retention-days: 1
+          overwrite: true

From e42143c88510b3ed79ffaff7c12255c1b96de152 Mon Sep 17 00:00:00 2001
From: anakin87 <stefanofiorucci@gmail.com>
Date: Wed, 22 Oct 2025 17:45:05 +0200
Subject: [PATCH 03/14] api ref generation

---
 .github/workflows/docusaurus_sync.yml | 27 +++++++++++++++------------
 1 file changed, 15 insertions(+), 12 deletions(-)

diff --git a/.github/workflows/docusaurus_sync.yml b/.github/workflows/docusaurus_sync.yml
index bf40f7fc..bdedf80f 100644
--- a/.github/workflows/docusaurus_sync.yml
+++ b/.github/workflows/docusaurus_sync.yml
@@ -1,6 +1,8 @@
 name: Sync API reference with Docusaurus
 
 on:
+  # for testing purposes
+  pull_request:
   push:
     tags:
       - "v[0-9]+.[0-9]+.[0-9]+*"
@@ -38,15 +40,16 @@ jobs:
           pip install -U haystack-pydoc-tools
 
       - name: Generate API reference
-        working-directory: ${{ steps.pathfinder.outputs.project_path }}
-
-        run: pydoc-markdown pydoc/config_docusaurus.yml
-
-      - name: Upload API reference artifact
-        uses: actions/upload-artifact@v4
-        with:
-          name: ${{ steps.pathfinder.outputs.integration_name }}
-          path: ${{ steps.pathfinder.outputs.project_path }}/${{ steps.pathfinder.outputs.integration_name }}.md
-          if-no-files-found: error
-          retention-days: 1
-          overwrite: true
+        run: ./.github/utils/pydoc-markdown.sh "docs/pydoc/config_docusaurus/*"
+
+      - name: print files
+        run: ls -la temp
+
+      # - name: Upload API reference artifact
+      #   uses: actions/upload-artifact@v4
+      #   with:
+      #     name: ${{ steps.pathfinder.outputs.integration_name }}
+      #     path: ${{ steps.pathfinder.outputs.project_path }}/${{ steps.pathfinder.outputs.integration_name }}.md
+      #     if-no-files-found: error
+      #     retention-days: 1
+      #     overwrite: true

From 4058cfb72e979c6c7e25068c328633ac380bc039 Mon Sep 17 00:00:00 2001
From: anakin87 <stefanofiorucci@gmail.com>
Date: Wed, 22 Oct 2025 17:49:35 +0200
Subject: [PATCH 04/14] retry

---
 .github/workflows/docusaurus_sync.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/docusaurus_sync.yml b/.github/workflows/docusaurus_sync.yml
index bdedf80f..0245f6ff 100644
--- a/.github/workflows/docusaurus_sync.yml
+++ b/.github/workflows/docusaurus_sync.yml
@@ -40,7 +40,7 @@ jobs:
           pip install -U haystack-pydoc-tools
 
       - name: Generate API reference
-        run: ./.github/utils/pydoc-markdown.sh "docs/pydoc/config_docusaurus/*"
+        run: ./.github/utils/pydoc-markdown.sh "../config_docusaurus/*"
 
       - name: print files
         run: ls -la temp

From 51671e5df7aa53324f03db10046caa4b29c7a5d4 Mon Sep 17 00:00:00 2001
From: anakin87 <stefanofiorucci@gmail.com>
Date: Wed, 22 Oct 2025 17:51:03 +0200
Subject: [PATCH 05/14] righ dir

---
 .github/workflows/docusaurus_sync.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/docusaurus_sync.yml b/.github/workflows/docusaurus_sync.yml
index 0245f6ff..4ce2183e 100644
--- a/.github/workflows/docusaurus_sync.yml
+++ b/.github/workflows/docusaurus_sync.yml
@@ -43,7 +43,7 @@ jobs:
         run: ./.github/utils/pydoc-markdown.sh "../config_docusaurus/*"
 
       - name: print files
-        run: ls -la temp
+        run: ls -la docs/pydoc/temp
 
       # - name: Upload API reference artifact
       #   uses: actions/upload-artifact@v4

From b6d0a7d2f88819bbe9c55290063665a7c994cdeb Mon Sep 17 00:00:00 2001
From: anakin87 <stefanofiorucci@gmail.com>
Date: Wed, 22 Oct 2025 18:04:14 +0200
Subject: [PATCH 06/14] progress

---
 .github/workflows/docusaurus_sync.yml | 88 ++++++++++++++++++++++++---
 1 file changed, 79 insertions(+), 9 deletions(-)

diff --git a/.github/workflows/docusaurus_sync.yml b/.github/workflows/docusaurus_sync.yml
index 4ce2183e..dfe8217b 100644
--- a/.github/workflows/docusaurus_sync.yml
+++ b/.github/workflows/docusaurus_sync.yml
@@ -42,14 +42,84 @@ jobs:
       - name: Generate API reference
         run: ./.github/utils/pydoc-markdown.sh "../config_docusaurus/*"
 
-      - name: print files
-        run: ls -la docs/pydoc/temp
+      - name: Upload API reference artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: experimental-api-reference
+          path: docs/pydoc/temp
+          if-no-files-found: error
+          retention-days: 1
+          overwrite: true
+
+
+  sync-api-reference:
+    runs-on: ubuntu-latest
+    needs: generate-api-reference
+
+    steps:
+      - name: Checkout Haystack repo
+        uses: actions/checkout@v5
+        with:
+          repository: deepset-ai/haystack
+          ref: main
+          token: ${{ secrets.HAYSTACK_BOT_TOKEN }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.10"
+
+      - name: Download API reference artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: experimental-api-reference
+          path: temp_api_reference
+
+      - name: Sync API reference
+        run: |
+          SOURCE_PATH="temp_api_reference"
+          DEST_PATH="docs-website/reference/experiments-api"
+          VERSIONED_DEST_PATH="docs-website/reference_versioned_docs"
+
+          echo "Syncing from $SOURCE_PATH to $DEST_PATH"
+          mkdir -p $DEST_PATH
+          # Using rsync to copy files. This will also remove files in dest that are no longer in source.
+          rsync -av --delete --exclude='.git/' "$SOURCE_PATH/" "$DEST_PATH/"
+
+          echo "Syncing to all versioned documentation paths"
+          # Find all version directories and sync to each one
+          for version_dir in "$VERSIONED_DEST_PATH"/version-*/experiments-api; do
+            echo "Syncing to $version_dir"
+            mkdir -p "$version_dir"
+            rsync -av --delete --exclude='.git/' "$SOURCE_PATH/" "$version_dir/"
+          done
+
+      - name: Show Git Status
+        run: |
+          cd docs-website
+          echo "=== Git Status ==="
+          git status --porcelain
+          echo ""
+          echo "=== Detailed Git Status ==="
+          git status
+          echo ""
+          echo "=== Files Changed ==="
+          git diff --name-status
+          echo ""
+          echo "=== Diff Summary ==="
+          git diff --stat
 
-      # - name: Upload API reference artifact
-      #   uses: actions/upload-artifact@v4
+      # - name: Create Pull Request
+      #   uses: peter-evans/create-pull-request@v7
+      #   env:
+      #     INTEGRATION_NAME: ${{ needs.generate-api-reference.outputs.integration_name }}
       #   with:
-      #     name: ${{ steps.pathfinder.outputs.integration_name }}
-      #     path: ${{ steps.pathfinder.outputs.project_path }}/${{ steps.pathfinder.outputs.integration_name }}.md
-      #     if-no-files-found: error
-      #     retention-days: 1
-      #     overwrite: true
+      #     token: ${{ secrets.HAYSTACK_BOT_TOKEN }}
+      #     commit-message: "Sync Core Integrations API reference (${{ env.INTEGRATION_NAME }}) on Docusaurus"
+      #     branch: sync-docusaurus-api-reference-${{ env.INTEGRATION_NAME }}
+      #     base: main
+      #     title: "docs: sync Core Integrations API reference (${{ env.INTEGRATION_NAME }}) on Docusaurus"
+      #     add-paths: |
+      #       docs-website
+      #     body: |
+      #       This PR syncs the Core Integrations API reference (${{ env.INTEGRATION_NAME }}) on Docusaurus. Just approve and merge it.

From ebfb3df87b064fc7ba63447e0d6a0e387615f6c2 Mon Sep 17 00:00:00 2001
From: anakin87 <stefanofiorucci@gmail.com>
Date: Wed, 22 Oct 2025 18:07:21 +0200
Subject: [PATCH 07/14] btter script

---
 .github/workflows/docusaurus_sync.yml | 19 +++++++++++++------
 1 file changed, 13 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/docusaurus_sync.yml b/.github/workflows/docusaurus_sync.yml
index dfe8217b..f69434e8 100644
--- a/.github/workflows/docusaurus_sync.yml
+++ b/.github/workflows/docusaurus_sync.yml
@@ -87,12 +87,19 @@ jobs:
           rsync -av --delete --exclude='.git/' "$SOURCE_PATH/" "$DEST_PATH/"
 
           echo "Syncing to all versioned documentation paths"
-          # Find all version directories and sync to each one
-          for version_dir in "$VERSIONED_DEST_PATH"/version-*/experiments-api; do
-            echo "Syncing to $version_dir"
-            mkdir -p "$version_dir"
-            rsync -av --delete --exclude='.git/' "$SOURCE_PATH/" "$version_dir/"
-          done
+          # Check if versioned docs directory exists and find existing version directories
+          if [ -d "$VERSIONED_DEST_PATH" ]; then
+            for version_dir in "$VERSIONED_DEST_PATH"/version-*; do
+              if [ -d "$version_dir" ]; then
+                experiments_api_dir="$version_dir/experiments-api"
+                echo "Syncing to $experiments_api_dir"
+                mkdir -p "$experiments_api_dir"
+                rsync -av --delete --exclude='.git/' "$SOURCE_PATH/" "$experiments_api_dir/"
+              fi
+            done
+          else
+            echo "No versioned docs directory found at $VERSIONED_DEST_PATH"
+          fi
 
       - name: Show Git Status
         run: |

From b9df6dba59c0bf555c93c26187ad6cccbe2d5886 Mon Sep 17 00:00:00 2001
From: anakin87 <stefanofiorucci@gmail.com>
Date: Wed, 22 Oct 2025 18:10:25 +0200
Subject: [PATCH 08/14] try creating a PR

---
 .github/workflows/docusaurus_sync.yml | 42 +++++++++------------------
 1 file changed, 13 insertions(+), 29 deletions(-)

diff --git a/.github/workflows/docusaurus_sync.yml b/.github/workflows/docusaurus_sync.yml
index f69434e8..b3092727 100644
--- a/.github/workflows/docusaurus_sync.yml
+++ b/.github/workflows/docusaurus_sync.yml
@@ -101,32 +101,16 @@ jobs:
             echo "No versioned docs directory found at $VERSIONED_DEST_PATH"
           fi
 
-      - name: Show Git Status
-        run: |
-          cd docs-website
-          echo "=== Git Status ==="
-          git status --porcelain
-          echo ""
-          echo "=== Detailed Git Status ==="
-          git status
-          echo ""
-          echo "=== Files Changed ==="
-          git diff --name-status
-          echo ""
-          echo "=== Diff Summary ==="
-          git diff --stat
-
-      # - name: Create Pull Request
-      #   uses: peter-evans/create-pull-request@v7
-      #   env:
-      #     INTEGRATION_NAME: ${{ needs.generate-api-reference.outputs.integration_name }}
-      #   with:
-      #     token: ${{ secrets.HAYSTACK_BOT_TOKEN }}
-      #     commit-message: "Sync Core Integrations API reference (${{ env.INTEGRATION_NAME }}) on Docusaurus"
-      #     branch: sync-docusaurus-api-reference-${{ env.INTEGRATION_NAME }}
-      #     base: main
-      #     title: "docs: sync Core Integrations API reference (${{ env.INTEGRATION_NAME }}) on Docusaurus"
-      #     add-paths: |
-      #       docs-website
-      #     body: |
-      #       This PR syncs the Core Integrations API reference (${{ env.INTEGRATION_NAME }}) on Docusaurus. Just approve and merge it.
+      - name: Create Pull Request
+        uses: peter-evans/create-pull-request@v7
+        with:
+          token: ${{ secrets.HAYSTACK_BOT_TOKEN }}
+          commit-message: "Sync HaystackExperimental API reference on Docusaurus"
+          branch: sync-docusaurus-api-reference-experimental
+          base: main
+          title: "docs: sync HaystackExperimental API reference on Docusaurus"
+          add-paths: |
+            docs-website
+          body: |
+            This PR syncs the HaystackExperimental API reference on Docusaurus. Just approve and merge it.
+          draft: true

From 22cb7d30b0e070e34828803fc1e3166bd826cc93 Mon Sep 17 00:00:00 2001
From: anakin87 <stefanofiorucci@gmail.com>
Date: Wed, 22 Oct 2025 18:14:43 +0200
Subject: [PATCH 09/14] fix acorn error

---
 haystack_experimental/components/query/query_expander.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/haystack_experimental/components/query/query_expander.py b/haystack_experimental/components/query/query_expander.py
index 0f273c48..c3febf3d 100644
--- a/haystack_experimental/components/query/query_expander.py
+++ b/haystack_experimental/components/query/query_expander.py
@@ -99,7 +99,7 @@ def __init__(
             If None, a default OpenAIChatGenerator with gpt-4.1-mini model is used.
         :param prompt_template: Custom [PromptBuilder](https://docs.haystack.deepset.ai/docs/promptbuilder)
             template for query expansion. The template should instruct the LLM to return a JSON response with the
-            structure: {"queries": ["query1", "query2", "query3"]}. The template should include 'query' and
+            structure: `{"queries": ["query1", "query2", "query3"]}`. The template should include 'query' and
             'n_expansions' variables.
         :param n_expansions: Number of alternative queries to generate (default: 4).
         :param include_original_query: Whether to include the original query in the output.

From e9e11d43155df42c5f7da3d913ae13e7ae2143a6 Mon Sep 17 00:00:00 2001
From: anakin87 <stefanofiorucci@gmail.com>
Date: Wed, 22 Oct 2025 18:23:54 +0200
Subject: [PATCH 10/14] simplify script

---
 .github/workflows/docusaurus_sync.yml | 35 +++++++++++----------------
 1 file changed, 14 insertions(+), 21 deletions(-)

diff --git a/.github/workflows/docusaurus_sync.yml b/.github/workflows/docusaurus_sync.yml
index b3092727..251be0c2 100644
--- a/.github/workflows/docusaurus_sync.yml
+++ b/.github/workflows/docusaurus_sync.yml
@@ -77,28 +77,21 @@ jobs:
 
       - name: Sync API reference
         run: |
-          SOURCE_PATH="temp_api_reference"
-          DEST_PATH="docs-website/reference/experiments-api"
-          VERSIONED_DEST_PATH="docs-website/reference_versioned_docs"
-
-          echo "Syncing from $SOURCE_PATH to $DEST_PATH"
-          mkdir -p $DEST_PATH
-          # Using rsync to copy files. This will also remove files in dest that are no longer in source.
-          rsync -av --delete --exclude='.git/' "$SOURCE_PATH/" "$DEST_PATH/"
-
-          echo "Syncing to all versioned documentation paths"
-          # Check if versioned docs directory exists and find existing version directories
-          if [ -d "$VERSIONED_DEST_PATH" ]; then
-            for version_dir in "$VERSIONED_DEST_PATH"/version-*; do
-              if [ -d "$version_dir" ]; then
-                experiments_api_dir="$version_dir/experiments-api"
-                echo "Syncing to $experiments_api_dir"
-                mkdir -p "$experiments_api_dir"
-                rsync -av --delete --exclude='.git/' "$SOURCE_PATH/" "$experiments_api_dir/"
-              fi
+          # Function to sync generated API reference to a destination
+          sync_to_dest() {
+            echo "Syncing to $1"
+            mkdir -p "$1"
+            rsync -av --delete --exclude='.git/' "temp_api_reference/" "$1/"
+          }
+
+          # Sync to main reference
+          sync_to_dest "docs-website/reference/experiments-api"
+
+          # Sync to all versioned directories
+          if [ -d "docs-website/reference_versioned_docs" ]; then
+            for version_dir in "docs-website/reference_versioned_docs"/version-*; do
+              [ -d "$version_dir" ] && sync_to_dest "$version_dir/experiments-api"
             done
-          else
-            echo "No versioned docs directory found at $VERSIONED_DEST_PATH"
           fi
 
       - name: Create Pull Request

From 00392eecf3ddca08302c8afb43e7a131247410e5 Mon Sep 17 00:00:00 2001
From: anakin87 <stefanofiorucci@gmail.com>
Date: Thu, 23 Oct 2025 10:15:42 +0200
Subject: [PATCH 11/14] new improvements

---
 .github/workflows/docusaurus_sync.yml | 18 +++++-------------
 1 file changed, 5 insertions(+), 13 deletions(-)

diff --git a/.github/workflows/docusaurus_sync.yml b/.github/workflows/docusaurus_sync.yml
index 251be0c2..f3338d58 100644
--- a/.github/workflows/docusaurus_sync.yml
+++ b/.github/workflows/docusaurus_sync.yml
@@ -7,19 +7,11 @@ on:
     tags:
       - "v[0-9]+.[0-9]+.[0-9]+*"
 
-  workflow_dispatch: # Activate this workflow manually
-    inputs:
-      tag:
-        description: "Tag with this format: v1.0.0. When running this workflow manually, version is irrelevant so you can use any value."
-        required: true
-        type: string
-        default: v1.0.0
-
-env:
-  # TAG: ${{ inputs.tag || github.ref_name }}
-
-  # for testing purposes
-  TAG: v1.0.0
+  # Manual trigger: Use this ONLY if the automatic API reference sync failed during a release.
+  # This will regenerate and sync the API reference to the Haystack repository.
+  # WARNING: Running this workflow when this repository has evolved significantly since the release
+  # will sync an incorrect API reference to Haystack.
+  workflow_dispatch:
 
 jobs:
   generate-api-reference:

From 2f620b38fed483b9dc26ec5a6429a1bcfd0bd7e6 Mon Sep 17 00:00:00 2001
From: anakin87 <stefanofiorucci@gmail.com>
Date: Thu, 23 Oct 2025 10:18:57 +0200
Subject: [PATCH 12/14] clean up

---
 .github/workflows/docusaurus_sync.yml | 2 --
 1 file changed, 2 deletions(-)

diff --git a/.github/workflows/docusaurus_sync.yml b/.github/workflows/docusaurus_sync.yml
index f3338d58..15c44ce3 100644
--- a/.github/workflows/docusaurus_sync.yml
+++ b/.github/workflows/docusaurus_sync.yml
@@ -1,8 +1,6 @@
 name: Sync API reference with Docusaurus
 
 on:
-  # for testing purposes
-  pull_request:
   push:
     tags:
       - "v[0-9]+.[0-9]+.[0-9]+*"

From 46c414b3674498c98f1648d0dc2e6e25b1990d22 Mon Sep 17 00:00:00 2001
From: anakin87 <stefanofiorucci@gmail.com>
Date: Thu, 23 Oct 2025 10:54:27 +0200
Subject: [PATCH 13/14] try again

---
 .github/workflows/docusaurus_sync.yml | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/.github/workflows/docusaurus_sync.yml b/.github/workflows/docusaurus_sync.yml
index 15c44ce3..5f432401 100644
--- a/.github/workflows/docusaurus_sync.yml
+++ b/.github/workflows/docusaurus_sync.yml
@@ -1,6 +1,8 @@
 name: Sync API reference with Docusaurus
 
 on:
+
+  pull_request:
   push:
     tags:
       - "v[0-9]+.[0-9]+.[0-9]+*"

From 3cae0e956679dcc9ef9d10f7ddba032f2c3a4aa0 Mon Sep 17 00:00:00 2001
From: anakin87 <stefanofiorucci@gmail.com>
Date: Thu, 23 Oct 2025 10:57:42 +0200
Subject: [PATCH 14/14] clean again

---
 .github/workflows/docusaurus_sync.yml | 9 +++------
 1 file changed, 3 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/docusaurus_sync.yml b/.github/workflows/docusaurus_sync.yml
index 5f432401..dd2b03c6 100644
--- a/.github/workflows/docusaurus_sync.yml
+++ b/.github/workflows/docusaurus_sync.yml
@@ -1,8 +1,6 @@
 name: Sync API reference with Docusaurus
 
 on:
-
-  pull_request:
   push:
     tags:
       - "v[0-9]+.[0-9]+.[0-9]+*"
@@ -90,12 +88,11 @@ jobs:
         uses: peter-evans/create-pull-request@v7
         with:
           token: ${{ secrets.HAYSTACK_BOT_TOKEN }}
-          commit-message: "Sync HaystackExperimental API reference on Docusaurus"
+          commit-message: "Sync Haystack Experimental API reference on Docusaurus"
           branch: sync-docusaurus-api-reference-experimental
           base: main
-          title: "docs: sync HaystackExperimental API reference on Docusaurus"
+          title: "docs: sync Haystack Experimental API reference on Docusaurus"
           add-paths: |
             docs-website
           body: |
-            This PR syncs the HaystackExperimental API reference on Docusaurus. Just approve and merge it.
-          draft: true
+            This PR syncs the Haystack Experimental API reference on Docusaurus. Just approve and merge it.