Repository: deepset-ai/haystack

Issue:
Allow docstring formatting to be reflected in documentation website
Function docstrings are currently being turned into API references for our website using pydoc markdown. However, this workflow does not allow for the formatting in function docstrings to be retained (see ElasticsearchRetriever.__init__()).

It would be good to find some pipeline that allows for docstrings to be turned into API references while keeping the formatting of the docstring so that code examples can be inserted here.


Discussion:
I guess we could find an easy solution here and just change the style how we structure the docstrings. Input needed regarding format and restrictions. If this is not possible, we need to debug the renderer and understand its behaviours. This would be rather time consuming. (Rnederer: https://github.com/NiklasRosenstein/pydoc-markdown/blob/cf625058dc1ab443a63e7e9abbbdf84dd39969b6/pydoc-markdown/src/pydoc_markdown/contrib/renderers/markdown.py)
This example could not be rendered by our pipeline: https://github.com/deepset-ai/haystack/commit/0cc66e153622054d1b40dfda0ec1b873cd754d46

Resolving patch:
diff --git a/haystack/retriever/dense.py b/haystack/retriever/dense.py
--- a/haystack/retriever/dense.py
+++ b/haystack/retriever/dense.py
@@ -49,6 +49,19 @@ def __init__(self,
         Init the Retriever incl. the two encoder models from a local or remote model checkpoint.
         The checkpoint format matches huggingface transformers' model format
 
+        **Example:**
+
+                ```python
+                # remote model from FAIR
+                DensePassageRetriever(document_store=your_doc_store,	
+                >                    query_embedding_model="facebook/dpr-question_encoder-single-nq-base",	
+                >                    passage_embedding_model="facebook/dpr-ctx_encoder-single-nq-base")	
+                # or from local path
+                DensePassageRetriever(document_store=your_doc_store,	
+                >                    query_embedding_model="model_directory/question-encoder",	
+                >                   passage_embedding_model="model_directory/context-encoder")
+                ```
+
         :param document_store: An instance of DocumentStore from which to retrieve documents.
         :param query_embedding_model: Local path or remote name of question encoder checkpoint. The format equals the
                                       one used by hugging-face transformers' modelhub models
diff --git a/haystack/retriever/sparse.py b/haystack/retriever/sparse.py
--- a/haystack/retriever/sparse.py
+++ b/haystack/retriever/sparse.py
@@ -25,29 +25,31 @@ def __init__(self, document_store: ElasticsearchDocumentStore, custom_query: str
                              names must match with the filters dict supplied in self.retrieve().
                              ::
 
-                                 An example custom_query:
+                                 **An example custom_query:**
+                                 ```python
                                  {
-                                    "size": 10,
-                                    "query": {
-                                        "bool": {
-                                            "should": [{"multi_match": {
-                                                "query": "${question}",                 // mandatory $question placeholder
-                                                "type": "most_fields",
-                                                "fields": ["text", "title"]}}],
-                                            "filter": [                                 // optional custom filters
-                                                {"terms": {"year": "${years}"}},
-                                                {"terms": {"quarter": "${quarters}"}},
-                                                {"range": {"date": {"gte": "${date}"}}}
-                                                ],
-
-                                        }
-                                    },
-                                 }
-
-                             For this custom_query, a sample retrieve() could be:
-                             ::
-                                 self.retrieve(query="Why did the revenue increase?",
-                                               filters={"years": ["2019"], "quarters": ["Q1", "Q2"]})
+                                >    "size": 10,
+                                >    "query": {
+                                >        "bool": {
+                                >            "should": [{"multi_match": {
+                                >                "query": "${question}",                 // mandatory $question placeholder
+                                >                "type": "most_fields",
+                                >                "fields": ["text", "title"]}}],
+                                >            "filter": [                                 // optional custom filters
+                                >                {"terms": {"year": "${years}"}},
+                                >                {"terms": {"quarter": "${quarters}"}},
+                                >                {"range": {"date": {"gte": "${date}"}}}
+                                >                ],
+                                >        }
+                                >    },
+                                }
+                                 ```
+
+                             **For this custom_query, a sample retrieve() could be:**
+                             ```python
+                            self.retrieve(query="Why did the revenue increase?",
+                                >          filters={"years": ["2019"], "quarters": ["Q1", "Q2"]})
+                            ```
         """
         self.document_store: ElasticsearchDocumentStore = document_store
         self.custom_query = custom_query


Test patch: