Add migration guide page (#2459)

* very early draft migration guide

* Update doc/source/getting_started/Installation.rst

Co-authored-by: Osvaldo A Martin <[email protected]>

* continue work on migration guide

* update migration guide

* improve dim/sample_dims section

* add migration guide to toctree

---------

Co-authored-by: Osvaldo A Martin <[email protected]>

Author: OriolAbril

doc/source/api/preview.md

@@ -1,11 +1,23 @@
 (preview_api)=
 
 # Preview
-This module give access to upcoming refactored features by exposing
+
+:::{py:module} arviz.preview
+This module gives access to upcoming refactored features by exposing
 all objects in [arviz-base](https://arviz-base.readthedocs.io/en/latest/),
 [arviz-stats](https://arviz-stats.readthedocs.io/en/latest/) and
 [arviz-plots](https://arviz-plots.readthedocs.io/en/latest/)
 under a single namespace: `arviz.preview`.
 
 In addition, there is also an `arviz.preview.info` to check availability
 of the different sub-libraries.
+:::
+
+
+:::{seealso}
+* Introduction to Exploratory Analysis of Bayesian Models and Bayesian workflow
+  through [arviz.preview](https://arviz-devs.github.io/EABM/)
+* The {ref}`migration_guide` introduces the new arviz-xyz libraries through
+  ``arviz.preview`` focusing on the differences with current ArviZ,
+  the reasons behind them and what new features can be unlocked through these changes.
+:::

doc/source/conf.py

@@ -333,6 +333,9 @@
     "sphinx": ("https://www.sphinx-doc.org/en/master/", None),
     "diataxis": ("https://diataxis.fr/", None),
     "arviz_org": ("https://www.arviz.org/en/latest/", None),
+    "arviz_base": ("https://arviz-base.readthedocs.io/en/latest/", None),
+    "arviz_stats": ("https://arviz-stats.readthedocs.io/en/latest/", None),
+    "arviz_plots": ("https://arviz-plots.readthedocs.io/en/latest/", None),
     "python": ("https://docs.python.org/3/", None),
 }
 

doc/source/getting_started/Installation.rst

@@ -7,6 +7,21 @@ functionality is available with the basic requirements, but ArviZ also has optio
 dependencies to further enhance the library. This guide will cover both basic and fully-fledged ArviZ installs and several installation methods.
 
 
+.. tip::
+
+   If you are installing ArviZ for the first time, consider installing with
+
+   .. code:: bash
+
+      pip install "arviz[preview]"
+
+   And using the library through the {mod}`arviz.preview` module.
+   While some features in ``arviz.`` are not available
+   in ``arviz.preview.``,  most have already been included.
+   Additionally, ``arviz.preview.`` include many new ones that
+   are not available in ``arviz.`` and never will be.
+
+
 ******
 Stable
 ******

doc/source/user_guide/index.rst

@@ -6,6 +6,7 @@ User Guide
 .. toctree::
   :maxdepth: 2
 
+  migration_guide
   plotting
   data_structures
   computation