Skip to content

Commit 2b1ca62

Browse files
AftabbsAftabbs
authored
docs(snippets): replace HTML comments with JSX comments for MDX v4 compatibility (#11117)
Replace all `<!-- test-ignore -->` HTML comment markers in Python docstrings and generated API reference docs with JSX comments `{/* test-ignore */}` to be compatible with strict MDX parsing in Docusaurus v4. Also update test_python_snippets.py to use the new JSX marker format for `TEST_IGNORE_MARK`, `TEST_CONCEPT_MARK`, `TEST_RUN_MARK`, and `TEST_REQUIRE_FILES_PREFIX` constants, and remove the `mdx1Compat: { comments: true }` compatibility setting from docusaurus.config.js. Closes #11104
1 parent bd0b4b1 commit 2b1ca62

45 files changed

Lines changed: 94 additions & 97 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎docs-website/docusaurus.config.js‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -38,9 +38,6 @@ const config = {
3838
},
3939

4040
markdown: {
41-
mdx1Compat: {
42-
comments: true,
43-
},
4441
hooks: {
4542
onBrokenMarkdownLinks: 'throw',
4643
},

‎docs-website/reference/haystack-api/audio_api.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ For the supported audio formats, languages, and other parameters, see the
1818

1919
### Usage example
2020

21-
<!-- test-ignore -->
21+
{/* test-ignore */}
2222

2323
```python
2424
from haystack.components.audio import LocalWhisperTranscriber

‎docs-website/reference/haystack-api/connectors_api.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ pass input arguments to this component.
2020

2121
Example:
2222

23-
<!-- test-ignore -->
23+
{/* test-ignore */}
2424

2525
```python
2626
from haystack.utils import Secret
@@ -167,7 +167,7 @@ variable in the code.
167167

168168
Usage example:
169169

170-
<!-- test-ignore -->
170+
{/* test-ignore */}
171171

172172
```python
173173
import json

‎docs-website/reference/haystack-api/converters_api.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ and a Document Intelligence or Cognitive Services resource. For help with settin
2020

2121
### Usage example
2222

23-
<!-- test-ignore -->
23+
{/* test-ignore */}
2424

2525
```python
2626
import os
@@ -379,7 +379,7 @@ Converts files to FileContent objects to be included in ChatMessage objects.
379379

380380
### Usage example
381381

382-
<!-- test-ignore -->
382+
{/* test-ignore */}
383383

384384
```python
385385
from haystack.components.converters import FileToFileContent
@@ -537,7 +537,7 @@ Documents are expected to have metadata containing:
537537

538538
### Usage example
539539

540-
<!-- test-ignore -->
540+
{/* test-ignore */}
541541

542542
```python
543543
from haystack import Document
@@ -1741,7 +1741,7 @@ see the [official documentation](https://github.com/apache/tika-docker/blob/main
17411741

17421742
Usage example:
17431743

1744-
<!-- test-ignore -->
1744+
{/* test-ignore */}
17451745

17461746
```python
17471747
from haystack.components.converters.tika import TikaDocumentConverter

‎docs-website/reference/haystack-api/embedders_api.md‎

Lines changed: 15 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ Calculates document embeddings using OpenAI models deployed on Azure.
1616

1717
### Usage example
1818

19-
<!-- test-ignore -->
19+
{/* test-ignore */}
2020

2121
```python
2222
from haystack import Document
@@ -139,7 +139,7 @@ Embeds strings using OpenAI models deployed on Azure.
139139

140140
### Usage example
141141

142-
<!-- test-ignore -->
142+
{/* test-ignore */}
143143

144144
```python
145145
from haystack.components.embedders import AzureOpenAITextEmbedder
@@ -257,7 +257,7 @@ Use it with the following Hugging Face APIs:
257257

258258
#### With free serverless inference API
259259

260-
<!-- test-ignore -->
260+
{/* test-ignore */}
261261

262262
```python
263263
from haystack.components.embedders import HuggingFaceAPIDocumentEmbedder
@@ -278,7 +278,7 @@ print(result["documents"][0].embedding)
278278

279279
#### With paid inference endpoints
280280

281-
<!-- test-ignore -->
281+
{/* test-ignore */}
282282

283283
```python
284284
from haystack.components.embedders import HuggingFaceAPIDocumentEmbedder
@@ -299,7 +299,7 @@ print(result["documents"][0].embedding)
299299

300300
#### With self-hosted text embeddings inference
301301

302-
<!-- test-ignore -->
302+
{/* test-ignore */}
303303

304304
```python
305305
from haystack.components.embedders import HuggingFaceAPIDocumentEmbedder
@@ -443,7 +443,7 @@ Use it with the following Hugging Face APIs:
443443

444444
#### With free serverless inference API
445445

446-
<!-- test-ignore -->
446+
{/* test-ignore */}
447447

448448
```python
449449
from haystack.components.embedders import HuggingFaceAPITextEmbedder
@@ -460,7 +460,7 @@ print(text_embedder.run("I love pizza!"))
460460

461461
#### With paid inference endpoints
462462

463-
<!-- test-ignore -->
463+
{/* test-ignore */}
464464

465465
```python
466466
from haystack.components.embedders import HuggingFaceAPITextEmbedder
@@ -476,7 +476,7 @@ print(text_embedder.run("I love pizza!"))
476476

477477
#### With self-hosted text embeddings inference
478478

479-
<!-- test-ignore -->
479+
{/* test-ignore */}
480480

481481
```python
482482
from haystack.components.embedders import HuggingFaceAPITextEmbedder
@@ -600,7 +600,7 @@ The embedding of each Document is stored in the `embedding` field of the Documen
600600

601601
### Usage example
602602

603-
<!-- test-ignore -->
603+
{/* test-ignore */}
604604

605605
```python
606606
from haystack import Document
@@ -756,7 +756,7 @@ Computes document embeddings using OpenAI models.
756756

757757
### Usage example
758758

759-
<!-- test-ignore -->
759+
{/* test-ignore */}
760760

761761
```python
762762
from haystack import Document
@@ -902,7 +902,7 @@ You can use it to embed user query and send it to an embedding Retriever.
902902

903903
### Usage example
904904

905-
<!-- test-ignore -->
905+
{/* test-ignore */}
906906

907907
```python
908908
from haystack.components.embedders import OpenAITextEmbedder
@@ -1042,7 +1042,7 @@ and send them to DocumentWriter to write into a Document Store.
10421042

10431043
### Usage example:
10441044

1045-
<!-- test-ignore -->
1045+
{/* test-ignore */}
10461046

10471047
```python
10481048
from haystack import Document
@@ -1195,7 +1195,7 @@ and send them to DocumentWriter to write a into a Document Store.
11951195

11961196
### Usage example:
11971197

1198-
<!-- test-ignore -->
1198+
{/* test-ignore */}
11991199

12001200
```python
12011201
from haystack import Document
@@ -1328,7 +1328,7 @@ You can use it to embed user query and send it to a sparse embedding retriever.
13281328

13291329
Usage example:
13301330

1331-
<!-- test-ignore -->
1331+
{/* test-ignore */}
13321332

13331333
```python
13341334
from haystack.components.embedders import SentenceTransformersSparseTextEmbedder
@@ -1451,7 +1451,7 @@ You can use it to embed user query and send it to an embedding retriever.
14511451

14521452
Usage example:
14531453

1454-
<!-- test-ignore -->
1454+
{/* test-ignore */}
14551455

14561456
```python
14571457
from haystack.components.embedders import SentenceTransformersTextEmbedder

‎docs-website/reference/haystack-api/extractors_api.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -467,7 +467,7 @@ in the documents.
467467

468468
Usage example:
469469

470-
<!-- test-ignore -->
470+
{/* test-ignore */}
471471

472472
```python
473473
from haystack import Document

‎docs-website/reference/haystack-api/generators_api.md‎

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ For details on OpenAI API parameters, see
2727

2828
### Usage example
2929

30-
<!-- test-ignore -->
30+
{/* test-ignore */}
3131

3232
```python
3333
from haystack.components.generators import AzureOpenAIGenerator
@@ -170,7 +170,7 @@ For details on OpenAI API parameters, see
170170

171171
### Usage example
172172

173-
<!-- test-ignore -->
173+
{/* test-ignore */}
174174

175175
```python
176176
from haystack.components.generators.chat import AzureOpenAIChatGenerator
@@ -388,7 +388,7 @@ For details on OpenAI API parameters, see
388388

389389
### Usage example
390390

391-
<!-- test-ignore -->
391+
{/* test-ignore */}
392392

393393
```python
394394
from haystack.components.generators.chat import AzureOpenAIResponsesChatGenerator
@@ -701,7 +701,7 @@ format for input and output. Use it to generate text with Hugging Face APIs:
701701

702702
#### With the serverless inference API (Inference Providers) - free tier available
703703

704-
<!-- test-ignore -->
704+
{/* test-ignore */}
705705

706706
```python
707707
from haystack.components.generators.chat import HuggingFaceAPIChatGenerator
@@ -727,7 +727,7 @@ print(result)
727727

728728
#### With the serverless inference API (Inference Providers) and text+image input
729729

730-
<!-- test-ignore -->
730+
{/* test-ignore */}
731731

732732
```python
733733
from haystack.components.generators.chat import HuggingFaceAPIChatGenerator
@@ -756,7 +756,7 @@ print(result)
756756

757757
#### With paid inference endpoints
758758

759-
<!-- test-ignore -->
759+
{/* test-ignore */}
760760

761761
```python
762762
from haystack.components.generators.chat import HuggingFaceAPIChatGenerator
@@ -776,7 +776,7 @@ print(result)
776776

777777
#### With self-hosted text generation inference
778778

779-
<!-- test-ignore -->
779+
{/* test-ignore */}
780780

781781
```python
782782
from haystack.components.generators.chat import HuggingFaceAPIChatGenerator
@@ -955,7 +955,7 @@ LLMs running locally may need powerful hardware.
955955

956956
### Usage example
957957

958-
<!-- test-ignore -->
958+
{/* test-ignore */}
959959

960960
```python
961961
from haystack.components.generators.chat import HuggingFaceLocalChatGenerator
@@ -1876,7 +1876,7 @@ Use the `HuggingFaceAPIChatGenerator` component, which supports the `chat_comple
18761876

18771877
#### With Hugging Face Inference Endpoints
18781878

1879-
<!-- test-ignore -->
1879+
{/* test-ignore */}
18801880

18811881
```python
18821882
from haystack.components.generators import HuggingFaceAPIGenerator
@@ -1892,7 +1892,7 @@ print(result)
18921892

18931893
#### With self-hosted text generation inference
18941894

1895-
<!-- test-ignore -->
1895+
{/* test-ignore */}
18961896

18971897
```python
18981898
from haystack.components.generators import HuggingFaceAPIGenerator
@@ -1910,7 +1910,7 @@ Be aware that this example might not work as the Hugging Face Inference API no l
19101910
`text_generation` endpoint. Use the `HuggingFaceAPIChatGenerator` for generative models through the
19111911
`chat_completion` endpoint.
19121912

1913-
<!-- test-ignore -->
1913+
{/* test-ignore */}
19141914

19151915
```python
19161916
from haystack.components.generators import HuggingFaceAPIGenerator

‎docs-website/reference/haystack-api/image_converters_api.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ Documents are expected to have metadata containing:
2424

2525
### Usage example
2626

27-
<!-- test-ignore -->
27+
{/* test-ignore */}
2828

2929
```python
3030
from haystack import Document

‎docs-website/reference/haystack-api/rankers_api.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ It can be used with a Text Embeddings Inference (TEI) API endpoint:
2929

3030
Usage example:
3131

32-
<!-- test-ignore -->
32+
{/* test-ignore */}
3333

3434
```python
3535
from haystack import Document

‎docs-website/reference/haystack-api/routers_api.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -867,7 +867,7 @@ The labels are specific to each model and can be found it its description on Hug
867867

868868
### Usage example
869869

870-
<!-- test-ignore -->
870+
{/* test-ignore */}
871871

872872
```python
873873
from haystack.core.pipeline import Pipeline

0 commit comments

Comments
 (0)