adding docs page about aesara

docs/index.rst

@@ -15,9 +15,8 @@ These features include:
   <https://celerite2.readthedocs.io>`_.
 * Fast and accurate limb darkened light curves using `starry
   <https://rodluger.github.io/starry>`_.
-* Common reparameterizations for `limb darkening parameters
-  <https://arxiv.org/abs/1308.0009>`_, and `planet radius and impact
-  parameter <https://arxiv.org/abs/1811.04859>`_.
+* Common reparameterizations for exoplanet-specific parameters
+  like `limb darkening <https://arxiv.org/abs/1308.0009>`_.
 * And many others!
 
 All of these functions and distributions include methods for efficiently
@@ -36,29 +35,31 @@ magnitude.
 <https://github.com/exoplanet-dev/exoplanet>`_ so if you have any trouble, `open an issue
 <https://github.com/exoplanet-dev/exoplanet/issues>`_ there.
 
-Where to find what you need
----------------------------
+.. admonition:: Where to find what you need
+   :class: hint
 
-1. For general installation and basic usage, continue scrolling to the table of
-contents below.
+   🖥 For general installation and basic usage, continue scrolling to the table of
+   contents below.
 
-2. For more in depth examples of *exoplanet* used for more realistic problems,
-go to the `Case studies page <https://gallery.exoplanet.codes>`_.
+   🖼 For more in depth examples of *exoplanet* used for more realistic problems,
+   go to the `Case studies page <https://gallery.exoplanet.codes>`_.
 
-3. For more information about scalable Gaussian Processes in PyMC3 (this was
-previously implemented as part of *exoplanet*), see the `celerite2 documentation
-page <httsp://celerite2.readthedocs.io>`_.
+   📈 For more information about scalable Gaussian Processes in PyMC3 (this was
+   previously implemented as part of *exoplanet*), see the `celerite2 documentation
+   page <httsp://celerite2.readthedocs.io>`_.
+
+   👉 For helper functions and PyMC3 extras that used to be implemented as part of
+   *exoplanet*, see the `pymc3-ext project
+   <https://github.com/exoplanet-dev/pymc3-ext>`_.
 
-4. For helper functions and PyMC3 extras that used to be implemented as part of
-*exoplanet*, see the `pymc3-ext project
-<https://github.com/exoplanet-dev/pymc3-ext>`_.
 
 .. toctree::
    :maxdepth: 2
    :caption: User Guide
 
    user/install
    tutorials/citation.ipynb
+   user/theano
    user/api
    user/dev
 

docs/user/theano.rst

@@ -0,0 +1,48 @@
+.. _theano:
+
+Theano vs. Aesara
+=================
+
+*exoplanet* is built on top of the excellent `PyMC3 library
+<https://docs.pymc.io/>`_ and it uses some of the more advanced features of
+PyMC3 to enable the complex models required for exoplanet data analysis. As a
+user of *exoplanet* you will become familiar with some of these details and, in
+particular, you will find yourself interacting with PyMC3's backend directly.
+When it was originally designed, PyMC3 was built on top of a library called
+Theano, but the development of that library has since been taken over by the
+PyMC developers and it was renamed to `Aesara <https://aesara.readthedocs.io>`_
+(there are more details, and you can read about those in `this blog post from
+the PyMC developers
+<https://pymc-devs.medium.com/the-future-of-pymc3-or-theano-is-dead-long-live-theano-d8005f8a0e9b>`_).
+Theano and Aesara are not completely compatible so this transition has been a
+little painful for downstream users, like you and the developers of *exoplanet*.
+In the long run, we will switch over to using Aesara directly instead of Theano,
+but in the meantime, since some users will have Theano installed and others will
+have Aesara installed, we have developed a small library that can help smooth
+this transition: `aesara-theano-fallback
+<https://github.com/exoplanet-dev/aesara-theano-fallback>`_. This will be
+installed automatically when you install *exoplanet*, but you can also install
+it directly using:
+
+.. code-block:: bash
+
+    python -m pip install aesara-theano-fallback
+
+Then, you can use this with syntax like the following:
+
+.. code-block:: python
+
+    import aesara_theano_fallback.tensor as tt
+
+and:
+
+.. code-block:: python
+
+    from aesara_theano_fallback import aesara as theano
+
+In both of these examples, the library will attempt to provide a consistent
+interface regardless of which backend is installed. That being said, this has
+only been designed to support the features used by *exoplanet* and `starry
+<https://github.com/rodluger/starry>`_, so your milage might vary. Check out
+`aesara-theano-fallback on GitHub for more information or to open issues
+<https://github.com/exoplanet-dev/aesara-theano-fallback>`_.