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

docs/src/lode_linear/index.rst

@@ -0,0 +1,59 @@
+:orphan:
+
+LODE Tutorial
+=============
+
+
+
+
+.. raw:: html
+
+    <div class="sphx-glr-thumbnails">
+
+
+.. raw:: html
+
+    <div class="sphx-glr-thumbcontainer" tooltip="This tutorial explains how Long range equivariant descriptors can be constructed using rascalin...">
+
+.. only:: html
+
+  .. image:: /lode_linear/images/thumb/sphx_glr_lode_tutorial_thumb.png
+    :alt:
+
+  :ref:`sphx_glr_lode_linear_lode_tutorial.py`
+
+.. raw:: html
+
+      <div class="sphx-glr-thumbnail-title">LODE Tutorial</div>
+    </div>
+
+
+.. raw:: html
+
+    </div>
+
+
+.. toctree::
+   :hidden:
+
+   /lode_linear/lode_tutorial
+
+
+.. only:: html
+
+  .. container:: sphx-glr-footer sphx-glr-footer-gallery
+
+    .. container:: sphx-glr-download sphx-glr-download-python
+
+      :download:`Download all examples in Python source code: lode_linear_python.zip </lode_linear/lode_linear_python.zip>`
+
+    .. container:: sphx-glr-download sphx-glr-download-jupyter
+
+      :download:`Download all examples in Jupyter notebooks: lode_linear_jupyter.zip </lode_linear/lode_linear_jupyter.zip>`
+
+
+.. only:: html
+
+ .. rst-class:: sphx-glr-signature
+
+    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_