Cleanup rst files

- Add linter for sphinx rst files
- Remove trailing spaces
- Convert README.md to README.rst (Preparations for later
  code sharing between REDME and docs)
- Use 88 chars/line for rst files

Author: PicoCentauri

README.md

@@ -0,0 +1,94 @@
+scikit-matter
+=============
+
+|tests| |codecov| |docs| |pypi| |conda| |docs|
+
+A collection of scikit-learn compatible utilities that implement methods born out of the
+materials science and chemistry communities.
+
+Installation
+------------
+
+You can install *scikit-matter* either via pip using
+
+.. code-block:: bash
+
+    pip install skmatter
+
+
+or conda
+
+.. code-block:: bash
+
+    conda install -c conda-forge skmatter
+
+
+You can then `import skmatter` in your code!
+
+Developing the package
+----------------------
+
+Start by installing the development dependencies:
+
+.. code-block:: bash
+
+    pip install tox black flake8
+
+
+Then this package itself
+
+.. code-block:: bash
+
+    git clone https://github.com/lab-cosmo/scikit-matter
+    cd scikit-matter
+    pip install -e .
+
+
+This install the package in development mode, making is ``import`` able globally and
+allowing you to edit the code and directly use the updated version.
+
+Running the tests
+^^^^^^^^^^^^^^^^^
+
+.. code-block:: bash
+
+    cd <scikit-matter PATH>
+    # run unit tests
+    tox
+    # run the code formatter
+    black --check .
+    # run the linter
+    flake8
+
+
+You may want to setup your editor to automatically apply the `black`_ code formatter
+when saving your files, there are plugins to do this with `all major editors`_.
+
+License and developers
+----------------------
+
+This project is distributed under the BSD-3-Clauses license. By contributing to it you
+agree to distribute your changes under the same license.
+
+.. _`black`: https://black.readthedocs.io/en/stable/
+.. _`all major editors`: https://black.readthedocs.io/en/stable/editor_integration.html
+
+.. |tests| image:: https://github.com/lab-cosmo/scikit-matter/workflows/Test/badge.svg
+   :alt: Github Actions Tests Job Status
+   :target: https://github.com/lab-cosmo/scikit-matter/actions?query=workflow%3ATests
+
+.. |codecov| image:: https://codecov.io/gh/lab-cosmo/scikit-matter/branch/main/graph/badge.svg?token=UZJPJG34SM
+   :alt: Code coverage
+   :target: https://codecov.io/gh/lab-cosmo/scikit-matter/
+
+.. |pypi| image:: https://img.shields.io/pypi/v/skmatter.svg
+   :alt: Latest PYPI version
+   :target: https://pypi.org/project/skmatter
+
+.. |conda| image:: https://anaconda.org/conda-forge/skmatter/badges/version.svg
+   :alt: Latest conda version
+   :target: https://anaconda.org/conda-forge/skmatter
+
+.. |docs| image:: https://img.shields.io/badge/documentation-latest-sucess
+   :alt: Documentation
+   :target: https://scikit-matter.readthedocs.io

README.rst

@@ -3,42 +3,39 @@ References
 
 .. [deJong1992]
     S. de Jong, H.A.L. Kiers,
-    "Principal covariates regression: Part I. Theory",
-    Chemom. intell. lab. syst. 14 (1992) 155-164
-    https://doi.org/10.1016/0169-7439(92)80100-I
+    "Principal covariates regression: Part I. Theory", Chemom. intell. lab. syst. 14
+    (1992) 155-164 https://doi.org/10.1016/0169-7439(92)80100-I
 
 .. [Imbalzano2018]
-    Giulio Imbalzano,  Andrea Anelli,  Daniele Giofré, Sinja Klees,  Jörg Behler, and  Michele Ceriotti,
-    “Automatic selection of atomic fingerprints and reference configurations for machine-learning potentials.”
-    The Journal of chemical physics 148 24 (2018): 241730.
-    https://aip.scitation.org/doi/10.1063/1.5024611.
+    Giulio Imbalzano, Andrea Anelli, Daniele Giofré,Sinja Klees, Jörg Behler, and
+    Michele Ceriotti, “Automatic selection of atomic fingerprints and reference
+    configurations for machine-learning potentials.” The Journal of chemical physics 148
+    24 (2018): 241730. https://aip.scitation.org/doi/10.1063/1.5024611.
 
 .. [Ceriotti2019]
-    Michele Ceriotti, Lyndon Emsley, Federico Paruzzo, Albert Hofstetter, Félix Musil, Sandip De, Edgar A. Engel, and Andrea Anelli.
-    "Chemical Shifts in Molecular Solids by Machine Learning Datasets",
-    Materials Cloud Archive 2019.0023/v2 (2019),
+    Michele Ceriotti, Lyndon Emsley, Federico Paruzzo, Albert Hofstetter, Félix Musil,
+    Sandip De, Edgar A. Engel, and Andrea Anelli. "Chemical Shifts in Molecular Solids
+    by Machine Learning Datasets", Materials Cloud Archive 2019.0023/v2 (2019),
     https://doi.org/10.24435/materialscloud:2019.0023/v2.
 
 .. [Helfrecht2020]
     Benjamin A Helfrecht, Rose K Cersonsky, Guillaume Fraux, and Michele Ceriotti,
-    "Structure-property maps with Kernel principal covariates regression."
-    2020 Mach. Learn.: Sci. Technol. 1 045021.
+    "Structure-property maps with Kernel principal covariates regression." 2020 Mach.
+    Learn.: Sci. Technol. 1 045021.
     https://iopscience.iop.org/article/10.1088/2632-2153/aba9ef.
 
 .. [Pozdnyakov2020]
-    Pozdnyakov, S. N., Willatt, M. J., Bartók, A. P., Ortner, C., Csányi, G., & Ceriotti, M. (2020).
-    "Incompleteness of Atomic Structure Representations."
-    Physical Review Letters, 125(16).
-    https://doi.org/10.1103/physrevlett.125.166001
+    Pozdnyakov, S. N., Willatt, M. J., Bartók, A. P., Ortner, C., Csányi, G., &
+    Ceriotti, M. (2020). "Incompleteness of Atomic Structure Representations." Physical
+    Review Letters, 125(16). https://doi.org/10.1103/physrevlett.125.166001
 
 .. [Goscinski2021]
-    Alexander Goscinski, Guillaume Fraux, Giulio Imbalzano, and Michele Ceriotti,
-    "The role of feature space in atomistic learning."
-    2021 Mach. Learn.: Sci. Technol. 2 025028.
-    https://iopscience.iop.org/article/10.1088/2632-2153/abdaf7.
+    Alexander Goscinski, Guillaume Fraux, Giulio Imbalzano, and Michele Ceriotti, "The
+    role of feature space in atomistic learning." 2021 Mach. Learn.: Sci. Technol. 2
+    025028. https://iopscience.iop.org/article/10.1088/2632-2153/abdaf7.
 
 .. [Cersonsky2021]
-    Rose K Cersonsky, Benjamin A Helfrecht, Edgar A. Engel, Sergei Kliavinek, and Michele Ceriotti,
-    "Improving Sample and Feature Selection with Principal Covariates Regression"
-    2021 Mach. Learn.: Sci. Technol. 2 035038.
+    Rose K Cersonsky, Benjamin A Helfrecht, Edgar A. Engel, Sergei Kliavinek, and
+    Michele Ceriotti, "Improving Sample and Feature Selection with Principal Covariates
+    Regression" 2021 Mach. Learn.: Sci. Technol. 2 035038.
     https://iopscience.iop.org/article/10.1088/2632-2153/abfe7c.

docs/src/bibliography.rst

@@ -64,7 +64,7 @@
 master_doc = "index"
 
 project = "scikit-matter"
-author = ", ".join(open(os.path.join(ROOT, "contributors.txt")))
+author = ", ".join(open(os.path.join(ROOT, "contributors.txt")).read().splitlines())
 copyright = f"{datetime.now().date().year}, {author}"
 
 # The full version, including alpha/beta/rc tags

docs/src/conf.py

@@ -18,14 +18,14 @@ Then this package itself
   cd scikit-matter
   pip install -e .
 
-This install the package in development mode, making it importable globally
-and allowing you to edit the code and directly use the updated version.
+This install the package in development mode, making it importable globally and allowing
+you to edit the code and directly use the updated version.
 
 Running the tests
 #################
 
-The testsuite is implemented using Python's `unittest`_ framework and should be set-up and
-run in an isolated virtual environment with `tox`_. All tests can be run with
+The testsuite is implemented using Python's `unittest`_ framework and should be set-up
+and run in an isolated virtual environment with `tox`_. All tests can be run with
 
 .. code-block:: bash
 
@@ -40,11 +40,11 @@ If you wish to test only specific functionalities, for example:
   tox -e examples      # test the examples
 
 
-You can also use ``tox -e format`` to use tox to do actual formatting instead
-of just testing it. Also, you may want to setup your editor to automatically apply the
-`black <https://black.readthedocs.io/en/stable/>`_ code formatter when saving your
-files, there are plugins to do this with `all major
-editors <https://black.readthedocs.io/en/stable/editor_integration.html>`_.
+You can also use ``tox -e format`` to use tox to do actual formatting instead of just
+testing it. Also, you may want to setup your editor to automatically apply the `black
+<https://black.readthedocs.io/en/stable/>`_ code formatter when saving your files, there
+are plugins to do this with `all major editors
+<https://black.readthedocs.io/en/stable/editor_integration.html>`_.
 
 .. _unittest: https://docs.python.org/3/library/unittest.html
 .. _tox: https://tox.readthedocs.io/en/latest
@@ -60,9 +60,8 @@ machine as described above. Then, build the documentation with
 
     tox -e docs
 
-You can then visualize the local documentation with your favorite browser using
-the following command (or open the :file:`docs/build/html/index.html` file
-manually).
+You can then visualize the local documentation with your favorite browser using the
+following command (or open the :file:`docs/build/html/index.html` file manually).
 
 .. code-block:: bash
 
@@ -172,8 +171,8 @@ Then, show ``scikit-matter`` how to load your data by adding a loader function t
 
 Add this function to ``src/skmatter/datasets/__init__.py``.
 
-Finally, add a test to ``tests/test_datasets.py`` to see that your dataset
-loads properly. It should look something like this:
+Finally, add a test to ``tests/test_datasets.py`` to see that your dataset loads
+properly. It should look something like this:
 
 .. code-block:: python
 
@@ -190,7 +189,8 @@ loads properly. It should look something like this:
         self.my_data.DESCR
 
 
-You're good to go! Time to submit a `pull request. <https://github.com/lab-cosmo/scikit-matter/pulls>`_
+You're good to go! Time to submit a `pull request.
+<https://github.com/lab-cosmo/scikit-matter/pulls>`_
 
 
 License

docs/src/contributing.rst

@@ -7,5 +7,4 @@ Datasets
 
 .. include:: ../../src/skmatter/datasets/descr/nice_dataset.rst
 
-.. include:: ../../src/skmatter/datasets/descr/who_dataset.rst 
-
+.. include:: ../../src/skmatter/datasets/descr/who_dataset.rst

docs/src/datasets.rst

@@ -11,12 +11,12 @@ Reconstruction Measures
 Global Reconstruction Error
 ###########################
 
-.. autofunction:: pointwise_global_reconstruction_error 
-.. autofunction:: global_reconstruction_error 
+.. autofunction:: pointwise_global_reconstruction_error
+.. autofunction:: global_reconstruction_error
 
 .. _GRD-api:
 
-Global Reconstruction Distortion 
+Global Reconstruction Distortion
 ################################
 
 .. autofunction:: pointwise_global_reconstruction_distortion

docs/src/gfrm.rst

@@ -1,23 +1,23 @@
 scikit-matter documentation
 ===========================
 
-``scikit-matter`` is a collection of `scikit-learn <https://scikit.org/>`_
-compatible utilities that implement methods born out of the materials science
-and chemistry communities. 
+``scikit-matter`` is a collection of `scikit-learn <https://scikit.org/>`_ compatible
+utilities that implement methods born out of the materials science and chemistry
+communities.
 
-Convenient-to-use libraries such as scikit-learn have accelerated the adoption and application
-of machine learning (ML) workflows and data-driven methods. Such libraries have gained great
-popularity partly because the implemented methods are generally applicable in multiple domains.
-While developments in the atomistic learning community have put forward general-use machine
-learning methods, their deployment is commonly entangled with domain-specific functionalities,
-preventing access to a wider audience.
+Convenient-to-use libraries such as scikit-learn have accelerated the adoption and
+application of machine learning (ML) workflows and data-driven methods. Such libraries
+have gained great popularity partly because the implemented methods are generally
+applicable in multiple domains. While developments in the atomistic learning community
+have put forward general-use machine learning methods, their deployment is commonly
+entangled with domain-specific functionalities, preventing access to a wider audience.
 
 scikit-matter targets domain-agnostic implementations of methods developed in the
-computational chemical and materials science community, following the
-scikit-learn API and coding guidelines to promote usability and interoperability
-with existing workflows. scikit-matter contains a toolbox of methods for
-unsupervised and supervised analysis of ML datasets, including the comparison,
-decomposition, and selection of features and samples.
+computational chemical and materials science community, following the scikit-learn API
+and coding guidelines to promote usability and interoperability with existing workflows.
+scikit-matter contains a toolbox of methods for unsupervised and supervised analysis of
+ML datasets, including the comparison, decomposition, and selection of features and
+samples.
 
 .. toctree::
   :maxdepth: 1