docs improvements

Author: PicoCentauri

README.rst

@@ -2,8 +2,8 @@ scikit-matter
 =============
 |tests| |codecov| |pypi| |conda| |docs| |doi|
 
-A collection of scikit-learn compatible utilities that implement methods born out of the
-materials science and chemistry communities.
+A collection of ``scikit-learn`` compatible utilities that implement methods born out of
+the materials science and chemistry communities.
 
 For details, tutorials, and examples, please have a look at our `documentation`_.
 
@@ -72,7 +72,7 @@ Writing code is not the only way to contribute to the project. You can also:
 .. _`examples and tutorials`: https://scikit-matter.readthedocs.io/en/latest/contributing.html#contributing-new-examples
 .. _`new datasets`: https://scikit-matter.readthedocs.io/en/latest/contributing.html#contributing-datasets
 
-.. marker-contributors
+.. marker-citing
 
 Citing scikit-matter
 --------------------
@@ -81,7 +81,11 @@ If you use *scikit-matter* for your work, please cite:
 Goscinski A, Principe VP, Fraux G et al. scikit-matter :
 A Suite of Generalisable Machine Learning Methods Born out of Chemistry
 and Materials Science. Open Res Europe 2023, 3:81.
-`10.12688/openreseurope.15789.2 <https://doi.org/10.12688/openreseurope.15789.2>`_
+`10.12688/openreseurope.15789.2`_
+
+.. _`10.12688/openreseurope.15789.2`: https://doi.org/10.12688/openreseurope.15789.2
+
+.. marker-contributors
 
 Contributors
 ------------
@@ -90,18 +94,17 @@ Thanks goes to all people that make scikit-matter possible:
 .. image:: https://contrib.rocks/image?repo=scikit-learn-contrib/scikit-matter
    :target: https://github.com/scikit-learn-contrib/scikit-matter/graphs/contributors
 
-.. |tests| image:: https://github.com/scikit-learn-contrib/scikit-matter/workflows/Test/badge.svg
+.. |tests| image:: https://github.com/scikit-learn-contrib/scikit-matter/workflows/Tests/badge.svg
    :alt: Github Actions Tests Job Status
-   :target: (https://github.com/scikit-learn-contrib/scikit-matter/\
-                actions?query=workflow%3ATests)
+   :target: action_
 
 .. |codecov| image:: https://codecov.io/gh/scikit-learn-contrib/scikit-matter/branch/main/graph/badge.svg?token=UZJPJG34SM
    :alt: Code coverage
    :target: https://codecov.io/gh/scikit-learn-contrib/scikit-matter/
 
 .. |docs| image:: https://img.shields.io/badge/documentation-latest-sucess
    :alt: Python
-   :target: https://scikit-matter.readthedocs.io
+   :target: documentation_
 
 .. |pypi| image:: https://img.shields.io/pypi/v/skmatter.svg
    :alt: Latest PYPI version
@@ -113,4 +116,6 @@ Thanks goes to all people that make scikit-matter possible:
 
 .. |doi| image:: https://img.shields.io/badge/DOI-10.12688-blue
    :alt: ORE Paper
-   :target: https://doi.org/10.12688/openreseurope.15789.2
+   :target: `10.12688/openreseurope.15789.2`_
+
+.. _`action`: https://github.com/scikit-learn-contrib/scikit-matter/actions?query=branch%3Amain

docs/src/index.rst

@@ -74,6 +74,13 @@
    :start-after: marker-issues
    :end-before: marker-contributing
 
+.. include:: ../../README.rst
+   :start-after: marker-citing
+   :end-before: marker-contributors
+
+If you would like to contribute to scikit-matter, check out our :ref:`contributing`
+page!
+
 .. toctree::
   :hidden:
 
@@ -84,6 +91,3 @@
   contributing
   changelog
   bibliography
-
-If you would like to contribute to scikit-matter, check out our :ref:`contributing`
-page!

examples/README.rst

@@ -1,11 +1,11 @@
 Examples
 ========
 
-For a thorough tutorial of the methods introduced in `scikit-matter`, we
+For a thorough tutorial of the methods introduced in ``scikit-matter``, we
 suggest you check out the pedagogic notebooks in our companion project
 `kernel-tutorials <https://github.com/lab-cosmo/kernel-tutorials/>`_.
 
-For running the examples locally install `scikit-matter` with the ``examples``
+For running the examples locally install ``scikit-matter`` with the ``examples``
 optional dependencies.
 
 .. code-block:: bash

src/skmatter/_selection.py

@@ -592,19 +592,17 @@ def _compute_pi(self, X, y=None):
         the squares of the first :math:`k` components of the right singular vectors
 
         .. math::
-            \\pi_j =
-            \\sum_i^k \\left(\\mathbf{U}_\\mathbf{C}\\right)_{ij}^2.
+            \pi_j = \sum_i^k \left(\mathbf{U}_\mathbf{C}\right)_{ij}^2.
 
-        where :math:`\\mathbf{C} = \\mathbf{X}^T\\mathbf{X}`.
+        where :math:`\mathbf{C} = \mathbf{X}^T\mathbf{X}`.
 
-        For sample selection, the importance score :math:`\\pi` is the sum over the
+        For sample selection, the importance score :math:`\pi` is the sum over the
         squares of the first :math:`k` components of the right singular vectors
 
         .. math::
-            \\pi_j =
-            \\sum_i^k \\left(\\mathbf{U}_\\mathbf{K}\\right)_{ij}^2.
+            \pi_j = \sum_i^k \left(\mathbf{U}_\mathbf{K}\right)_{ij}^2.
 
-        where :math:`\\mathbf{K} = \\mathbf{X}\\mathbf{X}^T`.
+        where :math:`\mathbf{K} = \mathbf{X}\mathbf{X}^T`.
 
         Parameters
         ----------
@@ -615,7 +613,7 @@ def _compute_pi(self, X, y=None):
         Returns
         -------
         pi : numpy.ndarray of (n_to_select_from_)
-            :math:`\\pi` importance for the given samples or features
+            :math:`\pi` importance for the given samples or features
         """
         svd_kwargs = dict(k=self.k, random_state=self.random_state)
         if self._axis == 0:
@@ -941,7 +939,7 @@ def get_distance(self):
 
         For sample selection, this is a row-wise Euclidean distance, which can be
         expressed in terms of the Gram matrix
-        :math:`\\mathbf{K} = \mathbf{X} \\mathbf{X} ^ T`
+        :math:`\mathbf{K} = \mathbf{X} \mathbf{X} ^ T`
 
         .. math::
             \operatorname{d}_r(i, j) = K_{ii} - 2 K_{ij} + K_{jj}.

src/skmatter/datasets/descr/who_dataset.rst

@@ -3,7 +3,7 @@
 WHO dataset
 ###########
 
-`who_dataset.csv` is a compilation of multiple publically-available datasets
+``who_dataset.csv`` is a compilation of multiple publically-available datasets
 through data.worldbank.org. Specifically, the following versioned datasets are used:
 
 - NY.GDP.PCAP.CD (v2_4770383) [1]_
@@ -17,7 +17,7 @@ through data.worldbank.org. Specifically, the following versioned datasets are u
 - SP.DYN.LE00.IN (v2_4770556) [9]_
 - SP.POP.TOTL (v2_4770385) [10]_
 
-where the corresponding file names are `API_{dataset}_DS2_excel_en_{version}.xls`.
+where the corresponding file names are ``API_{dataset}_DS2_excel_en_{version}.xls``.
 
 This dataset, intended only for demonstration, contains 2020 country-year pairings and
 the corresponding values above.

src/skmatter/preprocessing/_data.py

@@ -225,7 +225,7 @@ class KernelNormalizer(KernelCenterer):
     where :math:`\phi` is a function mapping x to a Hilbert space.
     KernelNormalizer centers (i.e., normalize to have zero mean) the data without
     explicitly computing :math:`\phi(x)`.
-    It is equivalent to centering and scaling :math:`\\phi(x)` with
+    It is equivalent to centering and scaling :math:`\phi(x)` with
     sklearn.preprocessing.StandardScaler(with_std=False).
 
     Parameters

src/skmatter/sample_selection/_base.py

@@ -147,7 +147,7 @@ class PCovFPS(_PCovFPS):
     ----------
     mixing: float, default=0.5
         The PCovR mixing parameter, as described in PCovR as
-        :math:`{\\alpha}`
+        :math:`{\alpha}`
     initialize: int or 'random', default=0
         Index of the first selection. If 'random', picks a random value when fit starts.
     n_to_select : int or float, default=None
@@ -350,7 +350,7 @@ class PCovCUR(_PCovCUR):
     Parameters
     ----------
     mixing: float, default=0.5
-        The PCovR mixing parameter, as described in PCovR as :math:`{\\alpha}`. Stored
+        The PCovR mixing parameter, as described in PCovR as :math:`{\alpha}`. Stored
         in :py:attr:`self.mixing`.
     recompute_every : int
         number of steps after which to recompute the pi score defaults to 1, if 0 no

src/skmatter/sample_selection/_voronoi_fps.py

@@ -111,14 +111,14 @@ def score(self, X=None, y=None):
     def get_distance(self):
         r"""Traditional FPS employs a column-wise Euclidean distance for feature
         selection, which can be expressed using the covariance matrix
-        :math:`\\mathbf{C} = \\mathbf{X} ^ T \\mathbf{X}`.
+        :math:`\mathbf{C} = \mathbf{X} ^ T \mathbf{X}`.
 
         .. math::
             \operatorname{d}_c(i, j) = C_{ii} - 2 C_{ij} + C_{jj}.
 
         For sample selection, this is a row-wise Euclidean distance, which can be
         expressed in terms of the Gram matrix
-        :math:`\\mathbf{K} = \\mathbf{X} \\mathbf{X} ^ T`
+        :math:`\mathbf{K} = \mathbf{X} \mathbf{X} ^ T`
 
         .. math::
             \operatorname{d}_r(i, j) = K_{ii} - 2 K_{ij} + K_{jj}.

src/skmatter/utils/_orthogonalizers.py

@@ -87,15 +87,15 @@ def Y_feature_orthogonalizer(y, X, tol=1e-12, copy=True):
 
 
 def Y_sample_orthogonalizer(y, X, y_ref, X_ref, tol=1e-12, copy=True):
-    r"""Orthogonalizes a matrix of targets :math:`{\\mathbf{Y}}` given a reference
-    feature matrix :math:`{\\mathbf{X}_r}` and reference target matrix
-    :math:`{\\mathbf{Y}_r}`:
+    r"""Orthogonalizes a matrix of targets :math:`{\mathbf{Y}}` given a reference
+    feature matrix :math:`{\mathbf{X}_r}` and reference target matrix
+    :math:`{\mathbf{Y}_r}`:
 
     .. math::
-        \\mathbf{Y} \\leftarrow \\mathbf{Y} -
-        \\mathbf{X} \\left(\\mathbf{X}_{\\mathbf{r}}^T
-        \\mathbf{X}_{\\mathbf{r}}\\right)^{-1}\\mathbf{X}_{\\mathbf{r}}^T
-        \\mathbf{Y}_{\\mathbf{r}}
+        \mathbf{Y} \leftarrow \mathbf{Y} -
+        \mathbf{X} \left(\mathbf{X}_{\mathbf{r}}^T
+        \mathbf{X}_{\mathbf{r}}\right)^{-1}\mathbf{X}_{\mathbf{r}}^T
+        \mathbf{Y}_{\mathbf{r}}
 
     Parameters
     ----------

tox.ini

@@ -65,7 +65,7 @@ commands =
     black --check --diff {[tox]lint_folders}
     blackdoc --check --diff {[tox]lint_folders}
     isort --check-only --diff {[tox]lint_folders}
-    sphinx-lint --enable line-too-long --max-line-length 88 \
+    sphinx-lint --enable all --max-line-length 88 \
         -i "{toxinidir}/docs/src/examples" \
         {[tox]lint_folders} "{toxinidir}/README.rst"