[docs] Add param notes to DSL search.delete documentation, fix broken links (elastic#2861)

* Add param notes to DSL search.delete documentation, fix broken links

The preferred way of passing parameters to the DSL `Search.delete` appears to be calling `Search.params` first,
but this is only ever discussed in GitHub issues like
elastic/elasticsearch-dsl-py#1115
and elastic/elasticsearch-dsl-py#1395.

To help anyone else who has stumbled across this, I added a note about this to the documentation.

I also went ahead and updated the links for the `Search.scan` and `FacetedSearch.params`
methods to the most recent versions since they were 404ing.

* make sync and async changes the same

---------

Co-authored-by: Luna Lucadou <[email protected]>
Co-authored-by: Miguel Grinberg <[email protected]>

Author: 3 people

docs/reference/dsl_how_to_guides.md

@@ -84,6 +84,15 @@ s = Search(index='i').query(Match("title", "python"))
 response = s.delete()
 ```
 
+To pass [deletion parameters](https://elasticsearch-py.readthedocs.io/en/latest/api/elasticsearch.html#elasticsearch.Elasticsearch.delete_by_query)
+in your query, you can add them by calling ``params`` on the ``Search`` object before ``delete`` like this:
+
+```python
+s = Search(index='i').query("match", title="python")
+s = s.params(ignore_unavailable=False, wait_for_completion=True)
+response = s.delete()
+```
+
 
 #### Queries [_queries]
 

elasticsearch/dsl/_async/search.py

@@ -107,9 +107,9 @@ async def scan(self) -> AsyncIterator[_R]:
         Turn the search into a scan search and return a generator that will
         iterate over all the documents matching the query.
 
-        Use ``params`` method to specify any additional arguments you with to
+        Use the ``params`` method to specify any additional arguments you wish to
         pass to the underlying ``scan`` helper from ``elasticsearch-py`` -
-        https://elasticsearch-py.readthedocs.io/en/master/helpers.html#elasticsearch.helpers.scan
+        https://elasticsearch-py.readthedocs.io/en/latest/helpers.html#scan
 
         The ``iterate()`` method should be preferred, as it provides similar
         functionality using an Elasticsearch point in time.
@@ -123,7 +123,11 @@ async def scan(self) -> AsyncIterator[_R]:
 
     async def delete(self) -> AttrDict[Any]:
         """
-        delete() executes the query by delegating to delete_by_query()
+        ``delete()`` executes the query by delegating to ``delete_by_query()``.
+
+        Use the ``params`` method to specify any additional arguments you wish to
+        pass to the underlying ``delete_by_query`` helper from ``elasticsearch-py`` -
+        https://elasticsearch-py.readthedocs.io/en/latest/api/elasticsearch.html#elasticsearch.Elasticsearch.delete_by_query
         """
 
         es = get_connection(self._using)

elasticsearch/dsl/_sync/search.py

@@ -104,9 +104,9 @@ def scan(self) -> Iterator[_R]:
         Turn the search into a scan search and return a generator that will
         iterate over all the documents matching the query.
 
-        Use ``params`` method to specify any additional arguments you with to
+        Use the ``params`` method to specify any additional arguments you wish to
         pass to the underlying ``scan`` helper from ``elasticsearch-py`` -
-        https://elasticsearch-py.readthedocs.io/en/master/helpers.html#elasticsearch.helpers.scan
+        https://elasticsearch-py.readthedocs.io/en/latest/helpers.html#scan
 
         The ``iterate()`` method should be preferred, as it provides similar
         functionality using an Elasticsearch point in time.
@@ -118,7 +118,11 @@ def scan(self) -> Iterator[_R]:
 
     def delete(self) -> AttrDict[Any]:
         """
-        delete() executes the query by delegating to delete_by_query()
+        ``delete()`` executes the query by delegating to ``delete_by_query()``.
+
+        Use the ``params`` method to specify any additional arguments you wish to
+        pass to the underlying ``delete_by_query`` helper from ``elasticsearch-py`` -
+        https://elasticsearch-py.readthedocs.io/en/latest/api/elasticsearch.html#elasticsearch.Elasticsearch.delete_by_query
         """
 
         es = get_connection(self._using)

elasticsearch/dsl/faceted_search_base.py

@@ -469,7 +469,7 @@ def params(self, **kwargs: Any) -> None:
         """
         Specify query params to be used when executing the search. All the
         keyword arguments will override the current values. See
-        https://elasticsearch-py.readthedocs.io/en/master/api.html#elasticsearch.Elasticsearch.search
+        https://elasticsearch-py.readthedocs.io/en/latest/api/elasticsearch.html#elasticsearch.Elasticsearch.search
         for all available parameters.
         """
         self._s = self._s.params(**kwargs)