Merge pull request #24 from lab-cosmo/lint

Add linting including a gh action

.github/workflows/lint.yml

@@ -0,0 +1,23 @@
+# Lint tests run on PR
+# but should not run after push to main because reporting
+# these after push is meaningless to the building of the package
+name: lint
+
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: "3.10"
+    - run: pip install tox
+
+    - name: Test Lint
+      run: tox -e lint

.gitignore

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

CONDUCT.md

@@ -3,7 +3,11 @@
 
 ## 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.
+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
 
@@ -20,25 +24,44 @@ 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
+* 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 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.
+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.
+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.
+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.
+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).
+This Code of Conduct is adapted from the [Contributor Covenant, version
+1.4](http://contributor-covenant.org/version/1/4).

CONTRIBUTING.rst

@@ -1,35 +1,37 @@
 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.
+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.
+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.
+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 
+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
@@ -39,12 +41,21 @@ sphinx-gallery example. To convert your Jupyter notebook you can just use the
 Building the cookbook locally
 -----------------------------
 
-When you add a new example, you can build the doc and check if your code runs with
+When you add a new example, you can run the linter (code format checker) and build the
+doc to check if your code runs with
 
 .. code-block:: bash
 
     tox
 
+If there are formatting errors appearing you can format your file automatically with
+
+.. code-block:: bash
+
+    tox -e format
+
+That should fix most of the formatting issues automatically. If there are still
+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``.
 
@@ -54,14 +65,17 @@ 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.
+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
+If you still have problems adding your example to the repository, please feel free to
+contact one of the people
 
 `@agoscinski (Alexander Goscinski) <alexander.goscinski@epfl.ch>`_
 
@@ -70,4 +84,5 @@ If you still have problems adding your example to the repository, please feel fr
 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.
+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.

README.rst

@@ -5,12 +5,17 @@ COSMO Software Cookbook
 
 .. 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.  
+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. 
+If you want contribute an example, recipe or tutorial that combines multiple software
+tools together, check out the `contributing guidelines <CONTRIBUTING.rst>`_ first.

docs/src/conf.py

@@ -1,15 +1,16 @@
 # 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
+    "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_root = os.path.join(os.getcwd(), "../../examples/")
 examples_subdirs = []
 for path in os.listdir(examples_root):
     # ignores files and hidden directories
@@ -48,19 +49,21 @@
    :caption: Table of Contents
 
 """
-root_index_rst_content += ''.join([f"   {subdir}/index\n" for subdir in examples_subdirs])
+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:
+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),
+    "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),
@@ -69,7 +72,9 @@
     "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')),
+    "sklearn": (
+        "http://scikit-learn.org/stable",
+        (None, "./_intersphinx/sklearn-objects.inv"),
+    ),
     "skmatter": ("https://scikit-matter.readthedocs.io/en/latest/", None),
 }