improve documentation and code

- make mp4 animation in the gallery instead of gif
- add text to readme & usage
- split code into multiple file

Makefile

@@ -57,11 +57,14 @@ test-all: ## run tests on every Python version with tox
 
 doc: ## generate Sphinx HTML documentation, including API docs
 	sphinx-build -M html doc/source doc/build
+	cp doc/source/gallery/images/*.mp4 doc/build/html/_images/
 
 dclean:
 	rm -rf doc/build
 	rm -rf doc/source/_autosummary
 	rm -rf doc/source/gallery
+	# rm -rf animation/*
+	rm -rf example_built/*
 	find doc/ -name '*.pyc' -delete
 
 generate_ref:

README.rst

@@ -1,17 +1,19 @@
-Package to create animation of data
+Package to create animation with matplotlib
 
 
 ========
 Overview
 ========
 
+you define a fonction which build a matplotlib figure, and this package hold all the image generation, parallelisation and merge into a video.
 
 Features
 --------
 
-* TODO: fill it with the incredible feature from your project
-* incredible feature 1
-* incredible feature 2
+* build images in parallel
+* merge images with ffmpeg
+
+
 
 
 Installation

doc/source/conf.py

@@ -47,6 +47,8 @@
     "sphinx.ext.extlinks",
     "matplotlib.sphinxext.plot_directive",
     "sphinx_gallery.gen_gallery",
+    "sphinx_design",
+    "sphinxcontrib.video",
     # "myst_parser",
 ]
 # Add any paths that contain templates here, relative to this directory.

doc/source/usage.rst

@@ -2,11 +2,191 @@
 Usage
 =====
 
-To use animation-maker in a project::
+Animation-maker can be use in a python script or in command line.
+Please check the :ref:`gallery_reference` to see differents exemples of features.
 
+
+
+Basic example
+=============
+
+you want to create a small animation with matplotlib, to show how many points you need to draw a circle
+
+.. plot::
+    :include-source:
+
+    import matplotlib.pyplot as plt
+    import numpy as np
+
+    fig, ax = plt.subplots(1, 1, figsize=(4,4), dpi=120,)
+
+    ax.set_xlim(-1,1); ax.set_ylim(-1,1)
+
+    n = 7
+    x = np.arange(n+1)/n * 2*np.pi
+    ax.plot(np.sin(x), np.cos(x))
+    ax.set_title("n=7")
+
+
+
+you need to define a plotting function with this patern :
+
+.. code-block:: python
+
+    import matplotlib.pyplot as plt
+    import numpy as np
+
+    def plot(i, ds):
+        """
+        Parameters
+        ----------
+        i: int
+            indice of the image.
+        ds: xarray.Dataset
+            data passed to the plotting function
+
+
+        Returns
+        -------
+        fig: matplotlib.figure.Figure
+            the figure to save
+        """
+
+
+        fig, ax = plt.subplots(1, 1, figsize=(4,4), dpi=120,)
+
+        ax.set_xlim(-1,1); ax.set_ylim(-1,1)
+
+        n = i+7  # starts indices at 7
+        x = np.arange(n+1)/n * 2*np.pi
+        ax.plot(np.sin(x), np.cos(x))
+        ax.set_title(f"n={i}")
+        return fig
+
+
+We will explain the ``ds`` argument later.
+
+You should define all your plotting logic in this function, and return a matplotlib Figure.
+You can use the ``i`` parameter to know which image is being computed.
+
+now we have 2 choices to use the tool : the command line, or use in a python script.
+
+
+Use in a python script | jupyter notebook
+-----------------------------------------
+
+
+.. code-block:: python
+
+    import matplotlib.pyplot as plt
+    import numpy as np
     import anim
 
+    def plot(i, ds):
+        """
+        Parameters
+        ----------
+        i: int
+            indice of the image.
+        ds: xarray.Dataset
+            data passed to the plotting function
+
+
+        Returns
+        -------
+        fig: matplotlib.figure.Figure
+            the figure to save
+        """
+
+        fig, ax = plt.subplots(1, 1, figsize=(4,4), dpi=120,)
+        ax.set_xlim(-1,1); ax.set_ylim(-1,1)
+
+        n = i+7  # starts indices at 7
+        x = np.arange(n+1)/n * 2*np.pi
+        ax.plot(np.sin(x), np.cos(x))
+        ax.set_title(f"n={i}")
+        return fig
+
+    fps = 6
+    folder = "~/my_animation"
+    max_frames = fps * 7  # we want 7s of a video, with 6fps => 6*7=42 frames
+
+    anim.animate(plot, folder, fps, max_frames=max_frames)
+
+
+Use in command line
+-------------------
+
+To use in a command line, you must define a script file with all function needed, then use the command ``anim``:
+
+create the ``~/circle.py`` file
+
+.. code-block:: python
+    :linenos:
+    :caption: circle.py
+
+
+    import matplotlib.pyplot as plt
+    import numpy as np
+
+    ANIM_FPS = 6
+    ANIM_OUTPUT_FOLDER = "~/my_animation"
+    ANIM_MAX_FRAMES = ANIM_FPS * 4
+
+    def plot(i, ds):
+        """
+        Parameters
+        ----------
+        i: int
+            indice of the image.
+        ds: xarray.Dataset
+            data passed to the plotting function
+
+
+        Returns
+        -------
+        fig: matplotlib.figure.Figure
+            the figure to save
+        """
+
+        fig, ax = plt.subplots(1, 1, figsize=(4, 4), dpi=120)
+        ax.set_xlim(-1, 1)
+        ax.set_ylim(-1, 1)
+
+        n = i + 7  # starts indices at 7
+        x = np.arange(n + 1) / n * 2 * np.pi
+        ax.plot(np.sin(x), np.cos(x))
+        ax.set_title(f"image {i} : n={n}")
+        return fig
+
+then start
+
+.. code-block:: console
+
+    anim circle.py
+
+you can check the result in the example :ref:`small_reference`
+
+
+create a gif
+============
+
+You can create a gif from your video, and specify the length of the gif in seconds.
+(so it will take only the first X seconds from the video, and convert it to gif).
+The name of the gif will be the same as the video, with extension modified
+
+.. tab-set::
+
+    .. tab-item:: Python script
+
+        .. code-block:: python
+
+            # [...]
+            video_name = anim.animate(plot, folder, fps, max_frames=max_frames)
+            gif_name = anim.video2gif(video_name, gif_fps=5)  # <== specify duration of gif
+
+    .. tab-item:: console
 
-To use animation-maker in a command line::
+        .. code-block:: console
 
-    anim -h
+            anim circle.py -g 5  # <== specify duration of gif

environment_dev.yml

@@ -31,6 +31,8 @@ dependencies:
   - sphinx
   - pydata-sphinx-theme
   - sphinx-gallery
+  - sphinx_design
+  - sphinxcontrib-video
 
   #### dev
   - black

examples/README.rst

@@ -1,3 +1,5 @@
+.. _gallery_reference:
+
 Gallery
 -------
 

examples/plot_01_simple_animation.py

@@ -0,0 +1,43 @@
+"""
+.. _small_reference:
+
+Simple animation
+################
+
+explain the utilisation of the ``plot`` function
+
+"""
+
+import matplotlib.pyplot as plt
+import numpy as np
+
+ANIM_FPS = 6
+ANIM_OUTPUT_FOLDER = "animation/example_01"
+ANIM_MAX_FRAMES = ANIM_FPS * 7
+
+
+def plot(i, ds):
+    """
+    Parameters
+    ----------
+    i: int
+        indice of the image.
+    ds: xarray.Dataset
+        data passed to the plotting function
+
+
+    Returns
+    -------
+    fig: matplotlib.figure.Figure
+        the figure to save
+    """
+
+    fig, ax = plt.subplots(1, 1, figsize=(4, 4), dpi=120)
+    ax.set_xlim(-1, 1)
+    ax.set_ylim(-1, 1)
+
+    n = i + 7  # starts indices at 7
+    x = np.arange(n + 1) / n * 2 * np.pi
+    ax.plot(np.sin(x), np.cos(x))
+    ax.set_title(f"image {i} : n={n}")
+    return fig