test: running docstrings code snippets which generate API docs

.github/workflows/docs-website-test-docs-snippets.yml

@@ -11,22 +11,22 @@ on:
         default: 'main'
         type: string
 
-  # TEMPORARILY DISABLED
-  # push:
-  #   paths:
-  #     - 'docs-website/docs/**'
-  #     - 'docs-website/versioned_docs/**'
-  #     - 'docs-website/scripts/test_python_snippets.py'
-  #     - 'docs-website/scripts/generate_requirements.py'
-  #     - '.github/workflows/docs-website-test-docs-snippets.yml'
+env:
+  HATCH_VERSION: "1.16.5"
+  PYTHON_VERSION: "3.11"
 
 jobs:
   test-docs-snippets:
     runs-on: ubuntu-latest
-    timeout-minutes: 20
+    timeout-minutes: 30
     env:
-      # TODO: We'll properly set these after migration to core project
+      AZURE_OPENAI_ENDPOINT: ${{ secrets.AZURE_OPENAI_ENDPOINT }}
+      AZURE_OPENAI_AD_TOKEN: ${{ secrets.AZURE_OPENAI_AD_TOKEN }}
+      AZURE_OPENAI_API_KEY: ${{ secrets.AZURE_OPENAI_API_KEY }}
+      CORE_AZURE_CS_ENDPOINT: ${{ secrets.CORE_AZURE_CS_ENDPOINT }}
       OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+      SERPERDEV_API_KEY: ${{ secrets.SERPERDEV_API_KEY }}
+
     steps:
       - name: Checkout
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
@@ -36,34 +36,28 @@ jobs:
         with:
           python-version: '3.11'
 
+      - name: Install Hatch
+        run: pip install hatch==${{ env.HATCH_VERSION }}
+
+      - name: Generate API reference for Docusaurus
+        run: hatch run docs
+
       - name: Install base dependencies
         run: |
           python -m pip install --upgrade pip
           pip install requests toml
 
-      - name: Generate requirements.txt
-        run: |
-          # Use input version or default to main
-          if [ "${{ github.event.inputs.haystack_version }}" != "" ]; then
-            VERSION="${{ github.event.inputs.haystack_version }}"
-          else
-            VERSION="main"
-          fi
-          echo "Generating requirements.txt for Haystack version: $VERSION"
-          python docs-website/scripts/generate_requirements.py --version "$VERSION"
-
-      - name: Install dependencies
-        run: |
-          if [ -f requirements.txt ]; then
-            echo "Installing dependencies from requirements.txt"
-            pip install -r requirements.txt
-          else
-            echo "Error: requirements.txt was not generated"
-            exit 1
-          fi
-
       - name: Run snippet tests (verbose)
+        shell: bash
         run: |
-          # TEMPORARY: Testing with single file to make CI green
-          # TODO: Expand to run all docs: --paths docs versioned_docs
-          python docs-website/scripts/test_python_snippets.py docs-website/reference/haystack-api/agents_api.md
+          hatch -e test env run -- python docs-website/scripts/test_python_snippets.py --verbose tmp_api_reference/
+
+  notify-slack-on-failure:
+    if: failure() && github.ref_name == 'main'
+    needs:
+      - test-docs-snippets
+    runs-on: ubuntu-slim
+    steps:
+      - uses: deepset-ai/notify-slack-action@3cda73b77a148f16f703274198e7771340cf862b # v1
+        with:
+          slack-webhook-url: ${{ secrets.SLACK_WEBHOOK_URL_NOTIFICATIONS }}

docs-website/scripts/test_python_snippets.py

@@ -415,7 +415,7 @@ def main(argv: list[str] | None = None) -> int:
     parser.add_argument(
         "targets",
         nargs="*",
-        help=("Optional positional list of files or directories to scan. If omitted, --paths is used."),
+        help="Optional positional list of files or directories to scan. If omitted, --paths is used.",
     )
     parser.add_argument(
         "--paths",

haystack/components/audio/whisper_local.py

@@ -40,7 +40,7 @@ class LocalWhisperTranscriber:
     [GitHub repository](https://github.com/openai/whisper).
 
     ### Usage example
-
+    <!-- test-ignore -->
     ```python
     from haystack.components.audio import LocalWhisperTranscriber
 

haystack/components/connectors/openapi.py

@@ -24,22 +24,28 @@ class OpenAPIConnector:
     pass input arguments to this component.
 
     Example:
+    <!-- test-ignore -->
     ```python
     from haystack.utils import Secret
     from haystack.components.connectors.openapi import OpenAPIConnector
 
+    serper_dev_token = Secret.from_env_var("SERPERDEV_API_KEY")
+
+    def my_custom_config_factory():
+        # Create and return a custom configuration for the OpenAPIClient
+        pass
+
     connector = OpenAPIConnector(
         openapi_spec="https://bit.ly/serperdev_openapi",
-        credentials=Secret.from_env_var("SERPERDEV_API_KEY"),
-        service_kwargs={"config_factory": my_custom_config_factory}
+        credentials=serper_dev_token,
+        service_kwargs={"config_factory": my_custom_config_factory()}
     )
     response = connector.run(
         operation_id="search",
         arguments={"q": "Who was Nikola Tesla?"}
     )
     ```
     Note:
-    - The `parameters` argument is required for this component.
     - The `service_kwargs` argument is optional, it can be used to pass additional options to the OpenAPIClient.
 
     """

haystack/components/connectors/openapi_service.py

@@ -166,23 +166,27 @@ class OpenAPIServiceConnector:
     with tool calling capabilities. In the example below we use the tool call payload directly, but in a
     real-world scenario, the tool calls would usually be generated by the Chat Generator component.
 
-    Usage example:
+    You need to define the `serper_token` variable with your Serper.dev API token for the example to work.
+    Can be through the `SERPERDEV_API_KEY` environment variable or by directly assigning the token string to the
+    variable in the code.
 
+    Usage example:
+    <!-- test-ignore -->
     ```python
     import json
     import requests
 
     from haystack.components.connectors import OpenAPIServiceConnector
     from haystack.dataclasses import ChatMessage, ToolCall
-
+    from haystack.utils import Secret
 
     tool_call = ToolCall(
         tool_name="search",
         arguments={"q": "Why was Sam Altman ousted from OpenAI?"},
     )
     message = ChatMessage.from_assistant(tool_calls=[tool_call])
 
-    serper_token = "your_serper_dev_token"
+    serper_token = Secret.from_env_var("SERPERDEV_API_KEY").resolve_value()
     serperdev_openapi_spec = json.loads(requests.get("https://bit.ly/serper_dev_spec").text)
     service_connector = OpenAPIServiceConnector()
     result = service_connector.run(

haystack/components/converters/azure.py

@@ -38,7 +38,7 @@ class AzureOCRDocumentConverter:
     [Azure documentation](https://learn.microsoft.com/en-us/azure/ai-services/document-intelligence/quickstarts/get-started-sdks-rest-api).
 
     ### Usage example
-
+    <!-- test-ignore -->
     ```python
     import os
     from datetime import datetime

haystack/components/converters/csv.py

@@ -27,15 +27,18 @@ class CSVToDocument:
     It can attach metadata to the resulting documents.
 
     ### Usage example
-
     ```python
     from haystack.components.converters.csv import CSVToDocument
     from datetime import datetime
+
     converter = CSVToDocument()
-    results = converter.run(sources=["sample.csv"], meta={"date_added": datetime.now().isoformat()})
+    results = converter.run(
+        sources=["test/test_files/csv/sample_1.csv"], meta={"date_added": datetime.now().isoformat()}
+    )
     documents = results["documents"]
+
     print(documents[0].content)
-    # 'col1,col2\\nrow1,row1\\nrow2,row2\\n'
+    # >>  'col1,col2\\nrow1,row1\\nrow2,row2\\n'
     ```
     """
 

haystack/components/converters/docx.py

@@ -125,14 +125,19 @@ class DOCXToDocument:
     This component does not preserve page breaks in the original document.
 
     Usage example:
+
     ```python
     from haystack.components.converters.docx import DOCXToDocument, DOCXTableFormat, DOCXLinkFormat
+    from datetime import datetime
 
     converter = DOCXToDocument(table_format=DOCXTableFormat.CSV, link_format=DOCXLinkFormat.MARKDOWN)
-    results = converter.run(sources=["sample.docx"], meta={"date_added": datetime.now().isoformat()})
+    results = converter.run(
+        sources=["test/test_files/docx/sample_docx.docx"], meta={"date_added": datetime.now().isoformat()}
+    )
     documents = results["documents"]
+
     print(documents[0].content)
-    # 'This is a text from the DOCX file.'
+    # >> 'This is a text from the DOCX file.'
     ```
     """
 

haystack/components/converters/file_to_file_content.py

@@ -22,6 +22,7 @@ class FileToFileContent:
     Converts files to FileContent objects to be included in ChatMessage objects.
 
     ### Usage example
+    <!-- test-ignore -->
     ```python
     from haystack.components.converters import FileToFileContent
 

haystack/components/converters/html.py

@@ -27,10 +27,11 @@ class HTMLToDocument:
     from haystack.components.converters import HTMLToDocument
 
     converter = HTMLToDocument()
-    results = converter.run(sources=["path/to/sample.html"])
+    results = converter.run(sources=["test/test_files/html/paul_graham_superlinear.html"])
     documents = results["documents"]
+
     print(documents[0].content)
-    # 'This is a text from the HTML file.'
+    # > 'This is a text from the HTML file.'
     ```
     """