deploy: 56a181a

.gitignore

@@ -0,0 +1,5 @@
+docs/src/examples
+docs/src/index.rst
+
+*build*
+*egg-info/

.readthedocs.yml

@@ -0,0 +1,28 @@
+# .readthedocs.yml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools we need
+build:
+  os: ubuntu-22.04
+  apt_packages:
+    - cmake
+  tools:
+    python: "3.10"
+    rust: "1.64"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+   configuration: docs/src/conf.py
+
+# Declare the Python requirements required to build the docs
+python:
+   install:
+   - method: pip
+     path: .
+   - requirements: docs/requirements.txt
+   - requirements: docs/requirements-rascal.txt
+

CONDUCT.md

@@ -0,0 +1,44 @@
+
+# Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant, version 1.4](http://contributor-covenant.org/version/1/4).

CONTRIBUTING.rst

@@ -0,0 +1,73 @@
+Contributing
+============
+
+Contributions are welcome, and they are greatly appreciated! Every little bit
+helps, and credit will always be given. You can contribute in the ways listed below.
+
+Requirements for new contributions
+----------------------------------
+
+All code included in this repository is executed in each pull request.
+This ensures that the code in this repository stays executable for a longer time frame.
+Because of that we do not want to have examples with heavy calculations that take more
+than 30 seconds to execute. If heavy calculations are needed, it might be a better option
+to put your 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
+---------------------------------
+
+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 documentation folder `docs/src <docs/src>`_.
+You will find all the examples Python scripts in the `examples/` folder of the repository. 
+Each example is put into one of the example category folders, e.g. `examples/sample_selection <examples/sample_selection>`_.
+If you do not know where to put your example, just put in the `examples/uncategorized <examples/uncategorized>`_
+folder and when doing a pull request, we will figure out where to put it.
+
+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
+
+.. code-block:: bash
+
+    python ipynb_to_gallery.py <notebook.ipynb>
+
+Building the cookbook locally
+-----------------------------
+
+When you add a new example, you can build the doc and check if your code runs with
+
+.. code-block:: bash
+
+    tox
+
+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 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.
+
+Chemiscope widgets are not currently integrated into our sphinx gallery.
+
+Support
+-------
+
+If you still have problems adding your example to the repository, please feel free to contact one of the people
+
+`@agoscinski (Alexander Goscinski) <[email protected]>`_
+
+`@davidetisi (Davide Tisi) <[email protected]>`_
+
+Code of Conduct
+---------------
+
+Please note that the COSMO cookbook project is released with a `Contributor Code of Conduct <CONDUCT.md>`_. By contributing to this project you agree to abide by its terms.

LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2023, cosmo software cookbook developers
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.rst

@@ -0,0 +1,16 @@
+COSMO Software Cookbook
+=======================
+
+`COSMO Software Cookbook <https://software-cookbook.rtfd.io/>`_
+
+.. marker-intro-start
+
+The COSMO cookbook contains recipes for atomic-scale modelling for materials and molecules, with a particular focus on machine learning and statistical sampling methods.
+Rather than focusing on the usage of a specific package (see the `COSMO github page <https://github.com/lab-cosmo>`_ for a list of available tools, and their documentations) this cookbook provides concrete examples of the solution of modeling problems using a combination of the various tools.  
+
+.. marker-intro-end
+
+Contributors
+------------
+
+If you want contribute an example, recipe or tutorial that combines multiple software tools together, check out the `contributing guidelines <CONTRIBUTING.rst>`_ first. 

docs/requirements-rascal.txt

@@ -0,0 +1,6 @@
+# rascal needs to be in a separate requirements file because we need to specify
+# the packages index-url for it te use the prebuilt from 
+# from https://github.com/Luthaf/nightly-wheels
+# extra-url does not work here because there is another rascal package on pypi
+--index-url https://luthaf.fr/nightly-wheels/
+rascal

docs/requirements.txt

@@ -0,0 +1,26 @@
+--extra-index-url https://luthaf.fr/nightly-wheels/
+# 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 @ git+https://github.com/lab-cosmo/equisolve.git@71b3dfd
+
+metatensor
+rascaline

docs/src/conf.py

@@ -0,0 +1,75 @@
+# 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 the documentation of objects in 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},
+}
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build"]
+
+project = "cosmo-software-cookbook"
+copyright = "BSD 3-Clause License, Copyright (c) 2023, COSMO software cookbook team"
+
+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),
+}

examples/README.rst

@@ -0,0 +1,3 @@
+Examples
+========
+

examples/lode_linear/README.rst

@@ -0,0 +1,3 @@
+LODE Tutorial
+=============
+