Documentation feedback: What is the Main Goal of Code Snippets in the Documentation?

[TaMaN2031A]

Hello,
Are the code snippets in the documentation created to be run successfully, or are they just part of code that doesn't necessarily work, but only discuss the idea, aiming at not creating a large code snippet that could make the reader lose the main idea?
For example, the code snippet at the end of the AsyncPipeline documentation page. The code is not complete: document_store, prompt_template, and data variables are not initialized, but are used. And there is also no component called retriever. However, it's searched for in the partial_outputs.
Thanks!

[sjrl]

Hey @TaMaN2031A great question! In the past our code snippets were meant to be illustrative but not necessarily fully working examples. For full working examples we usually directed users to our Cookbooks and Tutorials.

That being said we are in the process of migrating and improving our docs. One of those items includes making our code snippets fully runnable and tested in our CI. Some early work on that can be seen here #9967 and here #9997. So yes in the future we plan on making these snippets full running examples.

[TaMaN2031A]

I went through the docs_website subdirectory, and it's beautifully crafted! The idea of generating api documentation files directly from the source code is brilliant, and creating tests for the code snippets in the docstrings is equally brilliant.

However, I find that this documentation, which is located here in the repo, is not done in the same way.
The .mdx files in the repo in the docs-website/docs are serving as an archive for the website?

I'm assuming this because I suggested a tiny enhancement in the website, and it was accepted, but I'm not seeing this enhancement in the according .mdx file.

So, if I wanted to put a working code snippet in the (not api) documentation, should I suggest an edit on the website or make a PR on the .mdx files, or maybe both?

Thanks alot!

[sjrl]

Hey @TaMaN2031A I'm glad you like our docs! :D To answer your question we aren't fully done with our migration yet so the new docs based on the .mdx files is not fully live. Once it is you'll be able to make suggestions to those files directly through a similar interface in our website. We'll let you know once that's done!