more structure to utils docs

.readthedocs.yml

@@ -8,27 +8,22 @@ version: 2
 # Set the OS, Python version and other tools you might need
 build:
   os: ubuntu-22.04
+  apt_packages:
+    - cmake
   tools:
-    python: "3.11"
+    python: "3.10"
     rust: "1.70"
-  jobs:
-    post_install:
-      # install metatensor-models
-      - python -m pip install . --extra-index-url https://download.pytorch.org/whl/cpu
 
-# Build documentation in the "docs/" directory with Sphinx
+
+# Build documentation in the docs/ directory with Sphinx
 sphinx:
    configuration: docs/src/conf.py
    fail_on_warning: true
 
-# Optionally build your docs in additional formats such as PDF and ePub
-# formats:
-#    - pdf
-#    - epub
 
-# Optional but recommended, declare the Python requirements required
-# to build your documentation
-# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+# Declare the Python requirements required to build the docs
 python:
    install:
+   - method: pip
+     path: .
    - requirements: docs/requirements.txt

docs/requirements.txt

@@ -1,3 +1,4 @@
+tomli
 sphinx >= 4.0.0       # documentation generator
 sphinx-toggleprompt   # hide the prompt (>>>) in python doctests
 pygments >=2.11       # syntax highligthing

docs/src/conf.py

@@ -1,57 +1,80 @@
-# Configuration file for the Sphinx documentation builder.
-#
-# For the full list of built-in configuration values, see the documentation:
-# https://www.sphinx-doc.org/en/master/usage/configuration.html
-
 import os
-import re
+import sys
+from datetime import datetime
+
+import tomli  # Replace by tomllib from std library once docs are build with Python 3.11
+
+import metatensor_models
 
 
+ROOT = os.path.abspath(os.path.join("..", ".."))
+sys.path.insert(0, ROOT)
+
 # -- Project information -----------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
-project = 'metatensor-models'
-copyright = '2023, metatensor-models developers'
-author = 'metatensor-models developers'
+# The master toctree document.
+master_doc = "index"
 
-# Parse the version from the module.
-with open(os.path.join(os.path.dirname(__file__), '..', '..', 'src', 'metatensor_models', '__init__.py')) as f:
-    version = re.match(r".*__version__ = \"(.*?)\"", f.read(), re.S).group(1)
-release = version
+with open(os.path.join(ROOT, "pyproject.toml"), "rb") as fp:
+    project_dict = tomli.load(fp)["project"]
 
+project = project_dict["name"]
+author = ", ".join(a["name"] for a in project_dict["authors"])
 
-# -- General configuration ---------------------------------------------------
+copyright = f"{datetime.now().date().year}, {author}"
 
-needs_sphinx = "4.0.0"
+# The full version, including alpha/beta/rc tags
+release = metatensor_models.__version__
 
-python_use_unqualified_type_names = True
+
+# -- General configuration ---------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinx_rtd_dark_mode',
     "sphinx.ext.viewcode",
     "sphinx.ext.autodoc",
     "sphinx.ext.intersphinx",
     "sphinx_toggleprompt",
 ]
 
-default_dark_mode = True
+python_use_unqualified_type_names = True
 
 autoclass_content = "both"
 autodoc_member_order = "bysource"
 autodoc_typehints = "both"
 autodoc_typehints_format = "short"
 
 intersphinx_mapping = {
+    "ase": ("https://wiki.fysik.dtu.dk/ase/", None),
     "python": ("https://docs.python.org/3", None),
     "torch": ("https://pytorch.org/docs/stable/", None),
+    "metatensor": ("https://lab-cosmo.github.io/metatensor/latest/", None),
+    "rascaline": ("https://luthaf.fr/rascaline/latest/", None),
 }
 
-
 # -- Options for HTML output -------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_theme = 'alabaster'
-html_static_path = ['_static']
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "furo"
+
+html_theme_options = {
+    "footer_icons": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/ceriottm/MeshLODE",
+            "html": "",
+            "class": "fa-brands fa-github fa-2x",
+        },
+    ],
+}
+
+# font-awesome logos (used in the footer)
+html_css_files = [
+    "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/css/fontawesome.min.css",
+    "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/css/solid.min.css",
+    "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/css/brands.min.css",
+]

docs/src/dev-docs.rst → docs/src/dev-docs/index.rst

@@ -8,5 +8,5 @@ It includes documentation on how to add a new model, as well as the API of the u
 .. toctree::
    :maxdepth: 1
 
-   dev-docs/adding-models
-   dev-docs/utils-api
+   adding-models
+   utils/index

docs/src/dev-docs/utils/dataset.rst

@@ -0,0 +1,7 @@
+Dataset
+#######
+
+.. automodule:: metatensor_models.utils.data.dataset
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/src/dev-docs/utils/index.rst

@@ -0,0 +1,10 @@
+Utilitliy API
+=============
+
+This is the API for the ``utils`` module of ``metatensor-models``.
+
+.. toctree::
+   :maxdepth: 1
+
+   dataset
+   readers/index

docs/src/dev-docs/utils/readers/index.rst

@@ -0,0 +1,17 @@
+Structure and Target data Readers
+=================================
+
+The main entry point for reading structure and target information are the two reader
+functions
+
+.. automodule:: metatensor_models.utils.data.readers
+     :members:
+
+Based on the provided filename they chose which child reader they use. For details on
+these refer to their documentation
+
+.. toctree::
+   :maxdepth: 1
+
+   structure
+   target

docs/src/dev-docs/utils/readers/structure.rst

@@ -0,0 +1,13 @@
+Structure Readers
+#################
+
+Parsers for obtaining information from structures. All readers return a :py:class:`list`
+of :py:class:`rascaline.torch.system.System`. The mapping which reader is used for which
+file type is stored in
+
+.. autodata:: metatensor_models.utils.data.readers.structures.STRUCTURE_READERS
+
+Implemented Readers
+-------------------
+
+.. autofunction:: metatensor_models.utils.data.readers.structures.read_ase

docs/src/dev-docs/utils/readers/target.rst

@@ -0,0 +1,13 @@
+Target data Readers
+###################
+
+Parsers for obtaining information from structures. All readers return a of
+:py:class:`metatensor.torch.TensorMap`. The mapping which reader is used for which file
+type is stored in
+
+.. autodata:: metatensor_models.utils.data.readers.targets.TARGET_READERS
+
+Implemented Readers
+-------------------
+
+.. autofunction:: metatensor_models.utils.data.readers.targets.read_ase

docs/src/index.rst

@@ -9,4 +9,4 @@ This is a collection of atomistic models interfaced with ``metatensor``.
    quickstart
    how-to
    models
-   dev-docs
+   dev-docs/index

pyproject.toml

@@ -6,9 +6,7 @@ requires-python = ">=3.7"
 readme = "README.md"
 license = {text = "BSD-3-Clause"}
 description = "" # TODO
-authors = [
-    # TODO
-]
+authors = [{name = "metatensor-models developers"}]
 
 dependencies = [
     "ase",

src/metatensor_models/utils/data/dataset.py

@@ -41,7 +41,7 @@ def __getitem__(self, index):
 
         Args:
             index: The index of the item in the dataset.
-        
+
         Returns:
             A tuple containing the structure and targets for the given index.
         """
@@ -68,7 +68,7 @@ def collate_fn(batch):
     Args:
         batch: A list of samples, where each sample is a tuple containing a
             structure and targets.
-    
+
     Returns:
         A tuple containing the structures and targets for the batch.
     """

src/metatensor_models/utils/data/readers/structures/__init__.py

@@ -1,3 +1,4 @@
 from .ase import read_ase
 
 STRUCTURE_READERS = {".xyz": read_ase}
+""":py:class:`dict`: dictionary mapping file suffixes to a structure reader"""

src/metatensor_models/utils/data/readers/targets/__init__.py

@@ -1,3 +1,4 @@
 from .ase import read_ase
 
 TARGET_READERS = {".xyz": read_ase}
+""":py:class:`dict`: dictionary mapping file suffixes to a target structure reader"""