Improve backend documentation and get plot_forest to follow best prac…

…tices (#78) * start working on best practices and backend docs * use none backend as documentation base * add images for plotly and none * adapt minigallery directive * use none backend instead of arviz_plots.backend * gallery references and plot sizing improvements * fix typo * pylint * wait until using sphinx 8 * pseudo fix for empty minigallery * modify slightly auto sizing * Apply suggestions from code review Co-authored-by: Osvaldo A Martin <[email protected]> * add see also --------- Co-authored-by: Osvaldo A Martin <[email protected]>
arviz-devs · Aug 6, 2024 · 32a8702 · 32a8702
1 parent 60aac9a
commit 32a8702
Show file tree

Hide file tree

Showing 35 changed files with 353 additions and 479 deletions.
diff --git a/.gitignore b/.gitignore
@@ -99,10 +99,11 @@ docs/source/api/**/generated
 docs/source/gallery/_images
 docs/source/gallery/_scripts
 docs/source/gallery/*.md
+docs/source/gallery/backreferences.json
 docs/jupyter_execute
-docs/source/api/backend/matplotlib.rst
-docs/source/api/backend/bokeh.rst
-docs/source/api/backend/index.rst
+docs/source/api/backend/*.rst
+!docs/source/api/backend/*.part.rst
+!docs/source/api/backend/index.rst
 
 # PyBuilder
 .pybuilder/

diff --git a/docs/source/_static/no-image.svg b/docs/source/_static/no-image.svg
diff --git a/docs/source/_static/plotly-logo-dark.png b/docs/source/_static/plotly-logo-dark.png
diff --git a/docs/source/_static/plotly-logo-light.png b/docs/source/_static/plotly-logo-light.png
diff --git a/docs/source/api/backend/index.part.rst → docs/source/api/backend/index.rst b/docs/source/api/backend/index.part.rst → docs/source/api/backend/index.rst
@@ -6,7 +6,7 @@ Interface to plotting backends
 Available backends
 ------------------
 
-.. grid:: 2
+.. grid:: 1 1 2 2
 
     .. grid-item-card::
         :link: matplotlib
@@ -22,12 +22,44 @@ Available backends
         :img-background: ../../_static/bokeh-logo-light.svg
         :class-img-bottom: dark-light
 
+    .. grid-item-card::
+        :link: plotly
+        :link-type: doc
+        :link-alt: plotly
+        :img-background: ../../_static/plotly-logo-light.png
+        :class-img-bottom: dark-light
+
+    .. grid-item-card::
+        :link: none
+        :link-type: doc
+        :link-alt: none
+
+        .. grid:: 3
+
+           .. grid-item::
+
+              .. image:: ../../_static/no-image.svg
+                 :class: dark-light
+                 :alt:
+
+           .. grid-item::
+
+              Data
+
+           .. grid-item::
+
+              .. raw:: html
+
+                 <s>Viz</s>
+
 .. toctree::
    :maxdepth: 1
    :hidden:
 
    Matplotlib <matplotlib>
    Bokeh <bokeh>
+   Plotly <plotly>
+   None (only processing, no plotting) <none>
 
 ---------------------------
 Common interface definition
@@ -85,5 +117,3 @@ Common interface definition
 
     axis
         Data axis (x, y or both) on which to apply the function.
-
-.. autosummary of module elements will be added here from template
diff --git a/docs/source/api/backend/none.part.rst b/docs/source/api/backend/none.part.rst
@@ -0,0 +1,5 @@
+============
+None backend
+============
+
+.. automodule:: arviz_plots.backend.none
diff --git a/docs/source/api/backend/plotly.part.rst b/docs/source/api/backend/plotly.part.rst
@@ -0,0 +1,5 @@
+==============
+Plotly backend
+==============
+
+.. automodule:: arviz_plots.backend.plotly
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -56,7 +56,7 @@
 ]
 suppress_warnings = ["mystnb.unknown_mime_type"]
 
-backend_modules = ("index", "matplotlib", "bokeh")
+backend_modules = ("none", "matplotlib", "bokeh", "plotly")
 api_backend_dir = Path(__file__).parent.resolve() / "api" / "backend"
 with open(api_backend_dir / "interface.template.rst", "r", encoding="utf-8") as f:
     interface_template = f.read()

diff --git a/docs/source/gallery/distribution/plot_dist_ecdf.py b/docs/source/gallery/distribution/plot_dist_ecdf.py
@@ -1,5 +1,4 @@
 """
-(gallery_dist_ecdf)=
 # ECDF plot
 
 Facetted ECDF plots for 1D marginals of the distribution
@@ -8,8 +7,6 @@
 
 :::{seealso}
 API Documentation: {func}`~arviz_plots.plot_dist`
-
-Other gallery examples using `plot_dist`: {ref}`gallery_dist_kde`
 :::
 """
 from arviz_base import load_arviz_data

diff --git a/docs/source/gallery/distribution/plot_dist_kde.py b/docs/source/gallery/distribution/plot_dist_kde.py
@@ -1,5 +1,4 @@
 """
-(gallery_dist_kde)=
 # KDE plot
 
 Facetted KDE plots for 1D marginals of the distribution
@@ -8,8 +7,6 @@
 
 :::{seealso}
 API Documentation: {func}`~arviz_plots.plot_dist`
-
-Other gallery examples using `plot_dist`: {ref}`gallery_dist_ecdf`
 :::
 """
 from arviz_base import load_arviz_data

diff --git a/docs/source/gallery/distribution/plot_forest.py b/docs/source/gallery/distribution/plot_forest.py
@@ -1,5 +1,4 @@
 """
-(gallery_forest)=
 # Forest plot
 
 Default forest plot with marginal distribution summaries
@@ -8,8 +7,6 @@
 
 :::{seealso}
 API Documentation: {func}`~arviz_plots.plot_forest`
-
-Other gallery examples using `plot_forest`: {ref}`gallery_forest_shade`
 :::
 """
 from arviz_base import load_arviz_data

diff --git a/docs/source/gallery/distribution/plot_forest_shade.py b/docs/source/gallery/distribution/plot_forest_shade.py
@@ -1,5 +1,4 @@
 """
-(gallery_forest_shade)=
 # Forest plot with shading
 
 Forest plot marginal summaries with row shading to enhance reading
@@ -8,8 +7,6 @@
 
 :::{seealso}
 API Documentation: {func}`~arviz_plots.plot_forest`
-
-Other gallery examples using `plot_forest`: {ref}`gallery_forest`
 :::
 """
 from arviz_base import load_arviz_data

diff --git a/docs/source/gallery/distribution_comparison/plot_dist_models.py b/docs/source/gallery/distribution_comparison/plot_dist_models.py
@@ -1,5 +1,4 @@
 """
-(gallery_dist_models)=
 # Marginal distribution comparison plot
 
 Full marginal distribution comparison between different models
@@ -9,8 +8,6 @@
 :::{seealso}
 API Documentation: {func}`~arviz_plots.plot_dist`
 
-Other gallery examples using `plot_dist`: {ref}`gallery_dist_kde`, {ref}`gallery_dist_ecdf`
-
 Other examples comparing marginal distributions: {ref}`gallery_forest_models`
 :::
 """

diff --git a/docs/source/gallery/distribution_comparison/plot_forest_models.py b/docs/source/gallery/distribution_comparison/plot_forest_models.py
@@ -1,5 +1,4 @@
 """
-(gallery_forest_models)=
 # Forest plot comparison
 
 Forest plot summaries for 1D marginal distributions
@@ -9,8 +8,6 @@
 :::{seealso}
 API Documentation: {func}`~arviz_plots.plot_forest`
 
-Other gallery examples using `plot_forest`: {ref}`gallery_forest`, {ref}`gallery_forest_shade`
-
 Other examples comparing marginal distributions: {ref}`gallery_dist_models`
 :::
 """

diff --git a/docs/source/gallery/inference_diagnostics/plot_trace.py b/docs/source/gallery/inference_diagnostics/plot_trace.py
@@ -1,5 +1,4 @@
 """
-(gallery_trace)=
 # Trace plot
 
 Facetted plot with MCMC traces for each variable

diff --git a/docs/source/gallery/mixed/plot_forest_ess.py b/docs/source/gallery/mixed/plot_forest_ess.py
@@ -1,5 +1,4 @@
 """
-(gallery_forest_ess)=
 # Forest plot with ESS
 
 Multiple panel visualization with a forest plot and ESS information
@@ -8,8 +7,6 @@
 
 :::{seealso}
 API Documentation: {func}`~arviz_plots.plot_forest`
-
-Other gallery examples using `plot_forest`: {ref}`gallery_forest`, {ref}`gallery_forest_shade`
 :::
 """
 from importlib import import_module

diff --git a/docs/source/gallery/mixed/plot_trace_dist.py b/docs/source/gallery/mixed/plot_trace_dist.py
@@ -1,5 +1,4 @@
 """
-(gallery_trace_dist)=
 # Trace and distribution plot
 
 Two column layout with marginal distributions on the left and MCMC traces on the right

diff --git a/docs/source/gallery/model_criticism/plot_forest_pp_obs.py b/docs/source/gallery/model_criticism/plot_forest_pp_obs.py
@@ -1,5 +1,4 @@
 """
-(gallery_forest_pp_obs)=
 # Posterior predictive and observations forest plot
 
 Overlay of forest plot for the posterior predictive samples and the actual observations
@@ -8,8 +7,6 @@
 
 :::{seealso}
 API Documentation: {func}`~arviz_plots.plot_forest`
-
-Other gallery examples using `plot_forest`: {ref}`gallery_forest`, {ref}`gallery_forest_shade`
 :::
 """
 from importlib import import_module