deprecate discover() function

The discover() function was removed from the docs and was supposed to
be deprecated some time ago, but it didn't get a proper warning and
was still used in some examples.

This removes it from the examples and adds a warning so that it can
eventually be removed.

CHANGELOG.rst

@@ -26,6 +26,7 @@ Changed
 * The BlueZ D-Bus backend now uses ``dbus-fast`` instead of ``dbus-next`` which significantly improves performance.
 * The BlueZ D-Bus backend will not avoid trying to connect to devices that are already connected. Fixes #992.
 * Updated logging to lazy version and replaced format by f-string for BleakClientWinRT
+* Added deprecation warning to ``discover()`` method.
 
 Fixed
 -----

bleak/__init__.py

@@ -10,6 +10,7 @@
 import logging
 import platform
 import asyncio
+from warnings import warn
 
 from bleak.__version__ import __version__  # noqa: F401
 from bleak.exc import BleakError
@@ -80,9 +81,20 @@
 else:
     raise BleakError(f"Unsupported platform: {platform.system()}")
 
+
 # for backward compatibility
-if not _on_rtd:
-    discover = BleakScanner.discover
+def discover():
+    """
+    .. deprecated:: 0.17.0
+        This method will be removed in a future version of Bleak.
+        Use :meth:`BleakScanner.discover` instead.
+    """
+    warn(
+        "The discover function will removed in a future version, use BleakScanner.discover instead.",
+        FutureWarning,
+        stacklevel=2,
+    )
+    return BleakScanner.discover()
 
 
 def cli():

examples/disconnect_callback.py

@@ -10,11 +10,11 @@
 
 import asyncio
 
-from bleak import BleakClient, discover
+from bleak import BleakScanner, BleakClient
 
 
 async def main():
-    devs = await discover()
+    devs = await BleakScanner.discover()
     if not devs:
         print("No devices found, try again later.")
         return

examples/discover.py

@@ -9,11 +9,12 @@
 """
 
 import asyncio
-from bleak import discover
+
+from bleak import BleakScanner
 
 
 async def main():
-    devices = await discover()
+    devices = await BleakScanner.discover()
     for d in devices:
         print(d)