.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "auto_examples/multi_plots_for_sphinx.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        Click :ref:`here <sphx_glr_download_auto_examples_multi_plots_for_sphinx.py>`
        to download the full example code

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_auto_examples_multi_plots_for_sphinx.py:


Multi-Plots for Sphinx
======================

Using plotly in Sphinx is great to deliver interactivity in you documentation.
However, if you're using Sphinx to document your datascience project you'll likely come across the challenge of
wanting to execute plots within a loop. This snippet shows how to use the MultiPlot class to save multiple plots and
present them like subplots in your documentation.

.. GENERATED FROM PYTHON SOURCE LINES 11-15

.. code-block:: default


    # this next line provides the thumbnail, but you must have set save_as_png=True in the MultiPlot object.
    # sphinx_gallery_thumbnail_path = '_static/multi_plots_for_sphinx/figures.tagged.0.png'








.. GENERATED FROM PYTHON SOURCE LINES 16-24

.. code-block:: default


    from pathlib import Path

    import plotly.graph_objects as go

    from elphick.sklearn_viz.utils.file import script_path
    from elphick.sklearn_viz.utils.plotly import MultiPlot








.. GENERATED FROM PYTHON SOURCE LINES 25-29

Create some data and figures
----------------------------
We use a loop to generate the figures but instead of displaying them inside the loop,
we add them to a list.

.. GENERATED FROM PYTHON SOURCE LINES 29-46

.. code-block:: default


    ys = [
        [2, 3, 1],
        [1, 2, 2],
        [4, 2, 3],
        [3, 2, 5]
    ]

    # Define the directory where the .rst and .html files will be created
    static_dir: Path = script_path().parents[1] / 'docs' / 'source' / '_static'

    figs: list[go.Figure] = []
    for i, y in enumerate(ys):
        title = '-'.join([str(i) for i in y])
        fig = go.Figure(data=[go.Bar(y=y)], layout_title_text=title)
        figs.append(fig)








.. GENERATED FROM PYTHON SOURCE LINES 47-48

Save the figures to the _static directory of the docs using MultiPlot

.. GENERATED FROM PYTHON SOURCE LINES 48-51

.. code-block:: default


    MultiPlot(docs_static_dir=static_dir).save_plots(figs)








.. GENERATED FROM PYTHON SOURCE LINES 52-58

This rst directive will include the figures in the documentation. Note how a subdirectory is created in the
static folder using the stem of the script filename::

  .. include:: ../_static/multi_plots_for_sphinx/figures.rst

.. include:: ../_static/multi_plots_for_sphinx/figures.rst

.. GENERATED FROM PYTHON SOURCE LINES 60-64

Multiple Instances
------------------
If you need to use the MultiPlot class in multiple instances, you can use the tag parameter to ensure
the saved files are unique. This is useful when you want to save multiple sets of plots in the same script.

.. GENERATED FROM PYTHON SOURCE LINES 64-68

.. code-block:: default


    MultiPlot(docs_static_dir=static_dir, super_title="Second Instance using a tag",
              col_wrap=2, save_as_png=True, tag="tagged").save_plots(figs)








.. GENERATED FROM PYTHON SOURCE LINES 69-74

Here is how you include the images when using the tag parameter::

  .. include:: ../_static/multi_plots_for_sphinx/figures.tagged.rst

.. include:: ../_static/multi_plots_for_sphinx/figures.tagged.rst


.. rst-class:: sphx-glr-timing

   **Total running time of the script:** ( 0 minutes  0.380 seconds)


.. _sphx_glr_download_auto_examples_multi_plots_for_sphinx.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example


    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download Python source code: multi_plots_for_sphinx.py <multi_plots_for_sphinx.py>`

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download Jupyter notebook: multi_plots_for_sphinx.ipynb <multi_plots_for_sphinx.ipynb>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_