replacing the example / recipes with a tutorial page and improvements

.gitignore

@@ -15,8 +15,12 @@ examples/analysis_workflow/colored_trj.xyz
 examples/info_gain/trj_*.npy
 tests/systems/coex/.*
 tests/systems/.*
+.DS_Store
+.ice_water_ox.xtc_offsets.lock
+.ice_water_ox.xtc_offsets.npz
 
 .mypy_cache
 .pytest_cache
 .ruff_cache
 .venv
+

README.rst

@@ -81,10 +81,14 @@ Developer Setup
 
 .. _`just`: https://github.com/casey/just
 
-Examples
-========
+Tutorials and examples
+======================
+
+We provide and continuously update a set of tutorials to help new users to
+get started with ``dynsight``. They are available at the following link: 
+https://dynsight.readthedocs.io/en/latest/tutorials_menu.html.
 
-There are examples throughout the documentation and available in
+There are also examples throughout the documentation and available in
 the ``examples/`` directory of this repository.
 
 Related works and packages

docs/source/_static/recipes/getting_started.py

@@ -0,0 +1,45 @@
+"""Code from the Getting Started tutorial."""
+
+from pathlib import Path
+
+from dynsight.trajectory import Trj
+
+
+def main() -> None:
+    """Code from the Getting Started tutorial."""
+    # Loading an example trajectory
+    files_path = Path("Path/to/the/folder/where/files/are/stored")
+    trj = Trj.init_from_xtc(
+        traj_file=files_path / "ice_water_ox.xtc",
+        topo_file=files_path / "ice_water_ox.gro",
+    )
+    # Computing a descriptor
+    # Adjust n_jobs according to your computer capabilities
+    lens = trj.get_lens(r_cut=10, n_jobs=4)
+
+    # Performing Onion Clustering on the descriptor computed
+    lens_onion = lens.get_onion_smooth(delta_t=10)
+
+    # Plotting the results
+    lens_onion.plot_output(
+        file_path=files_path / "output_plot.png",
+        data_insight=lens,
+    )
+    lens_onion.plot_one_trj(
+        file_path=files_path / "single_trj.png",
+        data_insight=lens,
+        particle_id=1234,
+    )
+
+    # Exporting a colored trajectory based on the clustering results
+    trajslice = slice(0, -1, 1)
+    sliced_trj = trj.with_slice(trajslice=trajslice)
+
+    lens_onion.dump_colored_trj(
+        trj=sliced_trj,
+        file_path=files_path / "colored_trj.xyz",
+    )
+
+
+if __name__ == "__main__":
+    main()

docs/source/_static/recipes/spatial_denoising.py

@@ -0,0 +1,68 @@
+"""Code from the Spatial Denoising tutorial."""
+
+from pathlib import Path
+
+from dynsight.trajectory import Trj
+
+
+def main() -> None:
+    """Code from the Spatial Denoising tutorial."""
+    # Loading an example trajectory
+    files_path = Path("INPUT")
+    trj = Trj.init_from_xtc(
+        traj_file=files_path / "ice_water_ox.xtc",
+        topo_file=files_path / "ice_water_ox.gro",
+    )
+
+    # Computing SOAP descriptor
+    soap = trj.get_soap(
+        r_cut=10,
+        n_max=8,
+        l_max=8,
+        n_jobs=4,  # Adjust n_jobs according to your computer capabilities
+    )
+
+    # Computing TimeSOAP descriptor
+    _, tsoap = trj.get_timesoap(
+        soap_insight=soap,
+    )
+
+    # Performing Onion Clustering on the descriptor computed
+    tsoap.get_onion_analysis(
+        delta_t_min=2,
+        delta_t_num=20,
+        fig1_path=files_path / "onion_analysis.png",
+    )
+
+    # Applying Spatial Denoising
+    sliced_trj = trj.with_slice(slice(0, -1, 1))
+    sp_denoised_tsoap = tsoap.spatial_average(
+        trj=sliced_trj,
+        r_cut=10,
+        n_jobs=4,  # Adjust n_jobs according to your computer capabilities
+    )
+
+    # Performing Onion Clustering on the descriptor computed
+    sp_denoised_tsoap.get_onion_analysis(
+        delta_t_min=2,
+        delta_t_num=20,
+        fig1_path=files_path / "denoised_onion_analysis.png",
+    )
+
+    single_point_onion = tsoap.get_onion_smooth(
+        delta_t=37,
+    )
+    single_point_onion.dump_colored_trj(
+        sliced_trj, files_path / "onion_trj.xyz"
+    )
+
+    denoised_single_point_onion = sp_denoised_tsoap.get_onion_smooth(
+        delta_t=37,
+    )
+    denoised_single_point_onion.dump_colored_trj(
+        sliced_trj, files_path / "onion_trj_denoised.xyz"
+    )
+
+
+if __name__ == "__main__":
+    main()

docs/source/_static/style.css

@@ -21,3 +21,27 @@
         top: 0;
     }
 }
+
+.tutorial-card {
+  height: 280px;                 
+  display: flex;
+  flex-direction: column;
+  text-align: center;
+}
+
+.tutorial-card-img {
+  height: 180px;                
+  width: 100%;
+  object-fit: contain;           
+  margin: 0 auto;
+  display: block;
+}
+
+
+.tutorial-card-title {
+  margin-top: auto;             
+  padding-top: 10px;
+  font-weight: 600;
+  text-align: center;
+}
+

docs/source/conf.py

@@ -28,6 +28,7 @@
     "sphinx.ext.viewcode",
     "sphinx_copybutton",
     "sphinx.ext.mathjax",
+    "sphinx_design",
 ]
 
 # Check if SOAPify is available