Merge pull request #1071 from brian-team/start_deprecating_hears

Start deprecating brian2.hears

brian2/hears.py

@@ -1,6 +1,9 @@
 '''
 This is only a bridge for using Brian 1 hears with Brian 2.
 
+.. deprecated:: 2.2.2.2
+    Use the `brian2hears <https://brian2hears.readthedocs.io/>`_ package instead.
+
 NOTES:
 
 * Slicing sounds with Brian 2 units doesn't work, you need to either use Brian 1 units or replace calls to
@@ -17,7 +20,9 @@
     import brian as b1
     import brian.hears as b1h
 except ImportError:
-    raise ImportError("brian2.hears is a bridge between Brian 2 and the version of Brian Hears from "
+    raise ImportError("brian2.hears is deprecated and will be removed in a future release, please use the brian2hears "                        
+                      "package available at https://brian2hears.readthedocs.io/. If you really want to keep "
+                      "using it, note: brian2.hears is a bridge between Brian 2 and the version of Brian Hears from "
                       "Brian 1, you need to have Brian 1 installed to use it.")
 
 from brian2.core.clocks import Clock
@@ -32,7 +37,9 @@
 
 logger = get_logger(__name__)
 
-logger.warn("You are using the bridge between Brian 2 and Brian Hears from Brian 1. "
+logger.warn("brian2.hears is deprecated and will be removed in a future release, please use the brian2hears "                        
+            "package available at https://brian2hears.readthedocs.io/. If you really want to keep using it, note "
+            "that it is a bridge between Brian 2 and Brian Hears from Brian 1. "
             "This is not guaranteed to work in all cases that brian.hears works. "
             "See the limitations in the online documentation.")
 

docs_sphinx/introduction/brian1_to_2/brian1hears_bridge.rst

@@ -5,6 +5,9 @@ Brian Hears
 
 .. currentmodule:: brian2.hears
 
+.. deprecated:: 2.2.2.2
+    Use the `brian2hears <https://brian2hears.readthedocs.io/>`_ package instead.
+
 This module is designed for users of the Brian 1 library "Brian Hears". It allows you to use Brian Hears with Brian 2
 with only a few modifications (although it's not compatible with the "standalone" mode of Brian 2).
 The way it works is by acting as a "bridge" to the version in Brian 1. To

docs_sphinx/introduction/changes.rst

@@ -49,14 +49,22 @@ np.arange(2) * mV                   array([ 0.   ,  0.001])             array([
 
 Unported packages
 -----------------
-The following packages have not (yet) been ported to Brian 1. If your simulation
+The following packages have not (yet) been ported to Brian 2. If your simulation
 critically depends on them, you should consider staying with Brian 1 for now.
 
 * ``brian.tools``
-* ``brian.hears``  (the Brian 1 version can be used via `brian2.hears`, though,
-  see :ref:`brian_hears`)
 * ``brian.library.modelfitting``
-* ``brian.library.electrophysilogy``
+* ``brian.library.electrophysiology``
+
+Replacement packages
+--------------------
+The following packages that were included in Brian 1 have now been split into separate
+packages.
+
+* ``brian.hears`` has been updated to
+  `brian2hears <https://brian2hears.readthedocs.io/>`_. Note that there is a
+  legacy package ``brian2.hears`` included in ``brian2``, but this is now deprecated and
+  will be removed in a future release. For now, see :ref:`brian_hears` for details.
 
 Removed classes/functions and their replacements
 ------------------------------------------------