Repository: deepset-ai/haystack

Issue:
Haystack Documentation Backlog
Let's update the usage and API documentation for the following new components:

Summarizer
Translator
Squad to DPR script (Tutorial 9)
Knowledge Graph
Confidence
Evaluation

Website API and Usage for KG
Eval Nodes
Pipeline Config
Confidence Scores
Web Crawler

Add Import statements
Create snippets page






Discussion:
I love the usage example snippets and would love to see more there. Its extremely helpful to code things fast.

Could we also add import statements to those usage examples?
Adding imports is a good idea for sure. I think I like having code snippets inside the Usage pages, but I can also imagine it would be useful to have all of them on one page so you can quickly get to them.

Resolving patch:
diff --git a/haystack/eval.py b/haystack/eval.py
--- a/haystack/eval.py
+++ b/haystack/eval.py
@@ -13,21 +13,21 @@ class EvalRetriever:
     """
     This is a pipeline node that should be placed after a Retriever in order to assess its performance. Performance
     metrics are stored in this class and updated as each sample passes through it. To view the results of the evaluation,
-    call EvalRetriever.print()
+    call EvalRetriever.print(). Note that results from this Node may differ from that when calling Retriever.eval()
+    since that is a closed domain evaluation. Have a look at our evaluation tutorial for more info about
+    open vs closed domain eval (https://haystack.deepset.ai/docs/latest/tutorial5md).
     """
-    def __init__(self, debug=False, open_domain=True):
+    def __init__(self, debug: bool=False, open_domain: bool=True):
         """
         :param open_domain: When True, a document is considered correctly retrieved so long as the answer string can be found within it.
                             When False, correct retrieval is evaluated based on document_id.
-        :type open_domain: bool
         :param debug: When True, a record of each sample and its evaluation will be stored in EvalRetriever.log
-        :type debug: bool
         """
         self.outgoing_edges = 1
         self.init_counts()
         self.no_answer_warning = False
         self.debug = debug
-        self.log = []
+        self.log: List = []
         self.open_domain = open_domain
 
     def init_counts(self):
@@ -97,21 +97,21 @@ class EvalReader:
     """
     This is a pipeline node that should be placed after a Reader in order to assess the performance of the Reader
     individually or to assess the extractive QA performance of the whole pipeline. Performance metrics are stored in
-    this class and updated as each sample passes through it. To view the results of the evaluation, call EvalReader.print()
+    this class and updated as each sample passes through it. To view the results of the evaluation, call EvalReader.print().
+    Note that results from this Node may differ from that when calling Reader.eval()
+    since that is a closed domain evaluation. Have a look at our evaluation tutorial for more info about
+    open vs closed domain eval (https://haystack.deepset.ai/docs/latest/tutorial5md).
     """
 
-    def __init__(self, skip_incorrect_retrieval=True, open_domain=True, debug=False):
+    def __init__(self, skip_incorrect_retrieval: bool=True, open_domain: bool=True, debug: bool=False):
         """
         :param skip_incorrect_retrieval: When set to True, this eval will ignore the cases where the retriever returned no correct documents
-        :type skip_incorrect_retrieval: bool
         :param open_domain: When True, extracted answers are evaluated purely on string similarity rather than the position of the extracted answer
-        :type open_domain: bool
         :param debug: When True, a record of each sample and its evaluation will be stored in EvalReader.log
-        :type debug: bool
         """
         self.outgoing_edges = 1
         self.init_counts()
-        self.log = []
+        self.log: List = []
         self.debug = debug
         self.skip_incorrect_retrieval = skip_incorrect_retrieval
         self.open_domain = open_domain
diff --git a/haystack/summarizer/transformers.py b/haystack/summarizer/transformers.py
--- a/haystack/summarizer/transformers.py
+++ b/haystack/summarizer/transformers.py
@@ -22,9 +22,9 @@ class TransformersSummarizer(BaseSummarizer):
         **Example**
 
         ```python
-        |     docs = [Document(text="PG&E stated it scheduled the blackouts in response to forecasts for high winds amid dry conditions.
-        |            The aim is to reduce the risk of wildfires. Nearly 800 thousand customers were scheduled to be affected by
-        |            the shutoffs which were expected to last through at least midday tomorrow.")]
+        |     docs = [Document(text="PG&E stated it scheduled the blackouts in response to forecasts for high winds amid dry conditions."
+        |            "The aim is to reduce the risk of wildfires. Nearly 800 thousand customers were scheduled to be affected by"
+        |            "the shutoffs which were expected to last through at least midday tomorrow.")]
         |
         |     # Summarize
         |     summary = summarizer.predict(
@@ -40,7 +40,7 @@ class TransformersSummarizer(BaseSummarizer):
         |        "text": "California's largest electricity provider has turned off power to hundreds of thousands of customers.",
         |        ...
         |        "meta": {
-        |          "context": "PGE stated it scheduled the blackouts in response to forecasts for high winds amid dry conditions. ....
+        |          "context": "PGE stated it scheduled the blackouts in response to forecasts for high winds amid dry conditions. ..."
         |              },
         |        ...
         |      },
@@ -61,8 +61,8 @@ def __init__(
     ):
         """
         Load a Summarization model from Transformers.
-        See the up-to-date list of available models on
-        `huggingface.co/models <https://huggingface.co/models?filter=summarization>`__
+        See the up-to-date list of available models at
+        https://huggingface.co/models?filter=summarization
 
         :param model_name_or_path: Directory of a saved model or the name of a public model e.g.
                                    'facebook/rag-token-nq', 'facebook/rag-sequence-nq'.
diff --git a/haystack/translator/transformers.py b/haystack/translator/transformers.py
--- a/haystack/translator/transformers.py
+++ b/haystack/translator/transformers.py
@@ -73,6 +73,9 @@ def translate(
     ) -> Union[str, List[Document], List[str], List[Dict[str, Any]]]:
         """
         Run the actual translation. You can supply a query or a list of documents. Whatever is supplied will be translated.
+        :param query: The query string to translate
+        :param documents: The documents to translate
+        :param dict_key:
         """
         if not query and not documents:
             raise AttributeError("Translator need query or documents to perform translation")


Test patch: