Use separate conda env for each example

.gitignore

@@ -1,4 +1,4 @@
-docs/src/*
+docs/src/examples/
 
 *build*
 *egg-info/

CONTRIBUTING.rst

@@ -15,8 +15,8 @@ example in an external repository and link to it on the `Wiki page
 <https://github.com/lab-cosmo/software-cookbook/wiki>`_. If you feel unsure if a
 contribution is suitable, feel free to contact one of the `support`_ before.
 
-Adding an sphinx-gallery examples
----------------------------------
+Adding a new examples
+---------------------
 
 To visualize examples on our readthedocs page we use `sphinx-gallery`. When building the
 doc the examples are run and compiled automatically into HTML files and moved to the
@@ -27,16 +27,20 @@ If you do not know where to put your example, just put in the `examples/uncatego
 <examples/uncategorized>`_ folder and when doing a pull request, we will figure out
 where to put it.
 
+After adding a file, you'll need to update ``tox.ini`` to build your example when
+building the documentation. Look how it's done for the ``lode_linear`` example, and
+do the same for yours!
+
 Converting a Jupyter notebook to a sphinx-gallery compatible Python script
 --------------------------------------------------------------------------
 
 Often it is more convenient to work in a Jupyter notebook and convert in later to
 sphinx-gallery example. To convert your Jupyter notebook you can just use the
-`ipynb_to_gallery.py <ipynb_to_gallery.py>`_ file that is root folder of the repository
+`ipynb-to-gallery.py <ipynb_to_gallery.py>`_ file that is root folder of the repository
 
 .. code-block:: bash
 
-    python ipynb_to_gallery.py <notebook.ipynb>
+    python ipynb-to-gallery.py <notebook.ipynb>
 
 Building the cookbook locally
 -----------------------------
@@ -59,13 +63,10 @@ formatting issues remaining, then the reviewer of your pull request can fix them
 To visualize the generated cookbook open in a browser the file
 ``docs/build/html/index.html``.
 
-When you generate the examples locally all the notebook will be automatically generated
-in the folder ``docs/src/examples/<name of the example>``
-
 Known issues
 ------------
 
-Sometimes the doc preview from readthedocs is not correcty rendered. If something works
+Sometimes the doc preview from readthedocs is not rendered correctly. If something works
 in your local build but not in the readthedocs PR preview. It could that the issue is
 fixed once you merge with the main branch.
 

docs/requirements.txt

@@ -1,25 +1,4 @@
-# Sphinx
 sphinx
-sphinx_rtd_theme
 sphinx-gallery
 sphinx-toggleprompt
 furo
-
-# Jupyter widgets
-ipywidgets
-jupyter_sphinx
-
-# Scientific libraries
-matplotlib
-numpy
-ase
-scipy
-
-# COSMO stack and friends
-scikit-learn
-skmatter
-chemiscope
-equisolve @ https://github.com/lab-cosmo/equisolve/archive/63c9c54.zip
-
-metatensor
-rascaline @ https://github.com/luthaf/rascaline/archive/581d0ca.zip

docs/src/conf.py

@@ -1,30 +1,5 @@
-# Sphinx documentation build configuration file
-import os
-
-
 # Add any Sphinx extension module names here, as strings.
-extensions = [
-    "sphinx.ext.autodoc",  # import the modules you are documenting
-    "sphinx.ext.intersphinx",  # generate links to external projects
-    "sphinx.ext.viewcode",  # add links to highlighted source code
-    "sphinx_gallery.gen_gallery",  # provides a source parser for *.ipynb files
-]
-
-examples_root = os.path.join(os.getcwd(), "../../examples/")
-examples_subdirs = []
-for path in os.listdir(examples_root):
-    # ignores files and hidden directories
-    if os.path.isdir(os.path.join(examples_root, path)) and path[0] != ".":
-        examples_subdirs.append(path)
-
-sphinx_gallery_conf = {
-    "filename_pattern": "/*",
-    "examples_dirs": [f"../../examples/{subdir}" for subdir in examples_subdirs],
-    "gallery_dirs": [f"{subdir}" for subdir in examples_subdirs],
-    "min_reported_time": 60,
-    # Make the code snippet for own functions clickable
-    "reference_url": {"cosmo-software-cookbook": None},
-}
+extensions = ["sphinx.ext.viewcode", "sphinx_gallery.load_style"]
 
 templates_path = ["_templates"]
 exclude_patterns = ["_build"]
@@ -34,47 +9,3 @@
 
 htmlhelp_basename = "COSMO software-cookbook"
 html_theme = "furo"
-
-# We create the index.rst here because sphinx is not able to automatically
-# include all subdirectories using regex expression
-root_index_rst_content = r"""
-COSMO Software Cookbook
-=======================
-
-.. include:: ../../README.rst
-   :start-after: marker-intro-start
-   :end-before: marker-intro-end
-
-.. toctree::
-   :caption: Table of Contents
-
-"""
-root_index_rst_content += "".join(
-    [f"   {subdir}/index\n" for subdir in examples_subdirs]
-)
-print("Creating index.rst including all examples")
-print(root_index_rst_content)
-
-with open("index.rst", "w") as f:
-    f.write(root_index_rst_content)
-
-# Configuration for intersphinx: refer to the Python standard library
-# and other packages used by the cookbook
-
-intersphinx_mapping = {
-    "ase": ("https://wiki.fysik.dtu.dk/ase/", None),
-    "chemiscope": ("https://chemiscope.org/docs/", None),
-    "metatensor": ("https://lab-cosmo.github.io/metatensor/latest/", None),
-    "equisolve": ("https://lab-cosmo.github.io/equisolve/latest/", None),
-    "matplotlib": ("https://matplotlib.org/stable/", None),
-    "numpy": ("https://numpy.org/doc/stable/", None),
-    "python": ("https://docs.python.org/3", None),
-    "rascaline": ("https://luthaf.fr/rascaline/latest/", None),
-    "rascal": ("https://lab-cosmo.github.io/librascal/", None),
-    "scipy": ("https://docs.scipy.org/doc/scipy/", None),
-    "sklearn": (
-        "http://scikit-learn.org/stable",
-        (None, "./_intersphinx/sklearn-objects.inv"),
-    ),
-    "skmatter": ("https://scikit-matter.readthedocs.io/en/latest/", None),
-}

docs/src/index.rst

@@ -0,0 +1,14 @@
+COSMO Software Cookbook
+=======================
+
+.. include:: ../../README.rst
+   :start-after: marker-intro-start
+   :end-before: marker-intro-end
+
+.. toctree::
+   :caption: Table of Contents
+   :maxdepth: 1
+
+   examples/roy_gch/roy_gch
+   examples/lode_linear/lode_tutorial
+   examples/sample_selection/sample_selection_librascal

examples/lode_linear/environement.yml

@@ -0,0 +1,9 @@
+name: lode_linear
+dependencies:
+  - python=3.11
+  - pip
+  - pip:
+    - ase
+    - metatensor
+    - equisolve @ git+https://github.com/lab-cosmo/equisolve.git@63c9c54046507b27f115efb1d9b9fa8a1573c4da
+    - rascaline @ git+https://github.com/Luthaf/rascaline@581d0ca4dece424b4594c8c3cac40a7381e13ae5

examples/roy_gch/environement.yml

@@ -0,0 +1,10 @@
+name: lode_linear
+dependencies:
+  - python=3.11
+  - pip
+  - pip:
+    - chemiscope
+    - skmatter
+    - metatensor
+    - equisolve @ git+https://github.com/lab-cosmo/equisolve.git@63c9c54046507b27f115efb1d9b9fa8a1573c4da
+    - rascaline @ git+https://github.com/Luthaf/rascaline@581d0ca4dece424b4594c8c3cac40a7381e13ae5

examples/roy_gch/roy_gch.py

@@ -6,15 +6,15 @@
 `Beran et Al, Chemical Science
 (2022) <https://doi.org/10.1039/D1SC06074K>`__, comparing the
 conventional density-energy convex hull with a Generalized Convex Hull
-(GCH) analysis (see `Anelli et al., Phys. Rev. Materials
+(GCH) analysis (see `Anelli et al., Phys. Rev. Materials
 (2018) <https://doi.org/10.1103/PhysRevMaterials.2.103804>`__).
 It uses features computed with `rascaline <https://github.com/lab-cosmo/rascaline>`
 and uses the directional convex hull function from
 `scikit-matter <https://github.com/lab-cosmo/scikit-matter>`
 to make the figure.
 """
 import chemiscope
-import matplotlib.tri as mtri
+import matplotlib.tri
 import numpy as np
 from matplotlib import pyplot as plt
 from metatensor import mean_over_samples
@@ -40,7 +40,7 @@
 
 # %%
 # Energy-density hull
-# ===================
+# -------------------
 #
 # The Directional Convex Hull routines can be used to compute a
 # conventional density-energy hull
@@ -59,7 +59,7 @@
 # %%
 #
 # Hull energies
-# -------------
+# ^^^^^^^^^^^^^
 #
 # Structures on the hull are stable with respect to synthesis at constant
 # molar volume. Any other structure would lower the energy by decomposing
@@ -85,7 +85,7 @@
 
 # %%
 # Interactive visualization
-# -------------------------
+# ^^^^^^^^^^^^^^^^^^^^^^^^^
 #
 # You can also visualize the hull with ``chemiscope``.
 # This runs only in a notebook, and
@@ -116,7 +116,7 @@
 
 # %%
 # Generalized Convex Hull
-# =======================
+# -----------------------
 #
 # A GCH is a similar construction, in which generic structural descriptors
 # are used in lieu of composition, density or other thermodynamic
@@ -131,7 +131,7 @@
 
 # %%
 # Compute structural descriptors
-# ------------------------------
+# ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 #
 # A first step is to computes suitable ML descriptors. Here we have used
 # ``rascaline`` to evaluate average SOAP features for the structures.
@@ -163,7 +163,7 @@
 
 # %%
 # PCA projection
-# --------------
+# ^^^^^^^^^^^^^^
 #
 # Computes PCA projection to generate low-dimensional descriptors that
 # reflect structural diversity. Any other dimensionality reduction scheme
@@ -182,7 +182,7 @@
 
 # %%
 # Builds the Generalized Convex Hull
-# ----------------------------------
+# ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 #
 # Builds a convex hull on the first two PCA features
 
@@ -196,7 +196,7 @@
 # Generates a 3D Plot
 #
 
-triang = mtri.Triangulation(pca_features[sel, 0], pca_features[sel, 1])
+triang = matplotlib.tri.Triangulation(pca_features[sel, 0], pca_features[sel, 1])
 fig = plt.figure(figsize=(7, 5), tight_layout=True)
 ax = fig.add_subplot(projection="3d")
 ax.plot_trisurf(triang, energy[sel], color="gray")
@@ -239,7 +239,6 @@
                 "y": {"property": "pca_2"},
                 "z": {"property": "energy"},
                 "symbol": "type",
-                "symbol": "type",
                 "color": {"property": "hull_energy"},
                 "size": {
                     "factor": 35,

examples/sample_selection/environement.yml

@@ -0,0 +1,12 @@
+name: lode_linear
+dependencies:
+  - python=3.10
+  - pip
+  - pip:
+    # example dependencies
+    - chemiscope
+    - skmatter
+    - scikit-learn
+    - ase
+    # needed to install rascal
+    - setuptools