deepset-ai / deepset-ai/haystack
Use JSX comments for docstrings
Open
Beginner friendly
Nobody has claimed this yet.
P2
type:documentation
- Dominant language
- Python
- Stars
- 26.6k
- Forks
- 3.2k
- Avg merge
- 1d 3h
- Merged PRs (30d)
- 194
Description
We are not compatible with strict MDX since we use HTML comments in docstrings in relation to Python snippets testing.
See https://docusaurus.io/blog/releases/3.10#strict-comments.
We should:
- switch to JSX comments instead of HTML comments
- remove this compatibility setting: https://github.com/deepset-ai/haystack/blob/956921cc5b92a8b6d3366084de340feef15304af/docs-website/docusaurus.config.js#L41-L43
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Search the documentation files for HTML comments used around Python snippets, then inspect docs-website/docusaurus.config.js at the linked compatibility setting. Replace the identified comments with JSX comments, remove that setting, and verify that the documentation builds successfully with strict MDX comments enabled.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 72/100