Add documentation structure

.github/workflows/docs.yml

@@ -0,0 +1,27 @@
+name: Documentation
+
+on:
+  push:
+    branches: [main]
+    tags: ["*"]
+  pull_request:
+    # Check all PR
+
+jobs:
+  build:
+    runs-on: ubuntu-20.04
+    steps:
+      - uses: actions/checkout@v3
+      - name: setup Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.10"
+      - name: install dependencies
+        run: |
+          python -m pip install tox
+          sudo apt install doxygen
+      - name: build documentation
+        run: tox -e docs
+        env:
+          # Use the CPU-only version of torch
+          PIP_EXTRA_INDEX_URL: https://download.pytorch.org/whl/cpu

.github/workflows/pr-docs-preview.yml

@@ -0,0 +1,17 @@
+name: readthedocs/actions
+
+on:
+  pull_request_target:
+    types:
+      - opened
+
+permissions:
+  pull-requests: write
+
+jobs:
+  documentation-links:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: readthedocs/actions/preview@v1
+        with:
+          project-slug: metatensor-models

.readthedocs.yml

@@ -0,0 +1,30 @@
+# .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 OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+    rust: "1.70"
+
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+   configuration: docs/src/conf.py
+   fail_on_warning: true
+
+
+# Declare the Python requirements required to build the docs.
+# Additionally, a custom environment variable
+# PIP_EXTRA_INDEX_URL: https://download.pytorch.org/whl/cpu
+# is declared in the project’s dashboard
+python:
+   install:
+   - method: pip
+     path: .
+   - requirements: docs/requirements.txt

MANIFEST.in

@@ -10,5 +10,6 @@ prune .tox
 
 exclude .gitignore
 exclude tox.ini
+exclude .readthedocs.yml
 
 global-exclude *.py[cod] __pycache__/* *.so *.dylib

docs/requirements.txt

@@ -0,0 +1,4 @@
+furo
+sphinx >= 7
+sphinx-toggleprompt
+tomli

docs/src/conf.py

@@ -0,0 +1,80 @@
+import os
+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 -----------------------------------------------------
+
+# The master toctree document.
+master_doc = "index"
+
+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"])
+
+copyright = f"{datetime.now().date().year}, {author}"
+
+# The full version, including alpha/beta/rc tags
+release = metatensor_models.__version__
+
+
+# -- 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.ext.viewcode",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
+    "sphinx_toggleprompt",
+]
+
+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 -------------------------------------------------
+
+# 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": project_dict["urls"]["repository"],
+            "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/adding-models.rst

@@ -0,0 +1,4 @@
+Adding new models
+=================
+
+To be done.

docs/src/dev-docs/index.rst

@@ -0,0 +1,12 @@
+Developer documentation
+=======================
+
+This is a collection of documentation for developers of the metatensor-models package.
+It includes documentation on how to add a new model, as well as the API of the utils module.
+
+
+.. toctree::
+   :maxdepth: 1
+
+   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/how-to.rst

@@ -0,0 +1,4 @@
+How-to
+======
+
+This section describes how to use the ``metatensor-models`` package.

docs/src/index.rst

@@ -0,0 +1,12 @@
+Welcome to metatensor-models's documentation!
+=============================================
+
+This is a collection of atomistic models interfaced with ``metatensor``.
+
+.. toctree::
+   :maxdepth: 1
+
+   quickstart
+   how-to
+   models
+   dev-docs/index

docs/src/models.rst

@@ -0,0 +1,10 @@
+Available models
+================
+
+This is a list of the models available in ``metatensor-models``.
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   models/*

docs/src/models/soap-bpnn.rst

@@ -0,0 +1,4 @@
+SOAP-BPNN
+=========
+
+This is a Behler-Parrinello neural network with SOAP features.

docs/src/quickstart.rst

@@ -0,0 +1,8 @@
+Quickstart
+==========
+
+You can install metatensor-models with pip:
+
+.. code-block:: bash
+
+    pip install git+https://github.com/lab-cosmo/metatensor-models.git

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

@@ -10,8 +10,11 @@ class Dataset(torch.utils.data.Dataset):
     def __init__(
         self, structures: List[rascaline.torch.System], targets: Dict[str, TensorMap]
     ):
-        """Creates a dataset from a list of `rascaline.torch.System`s and
-        a list of dictionaries of `TensorMap`s."""
+        """
+        Creates a dataset from a list of `rascaline.torch.System` objects
+        and a dictionary of targets where the keys are strings and the
+        values are `TensorMap` objects.
+        """
 
         for tensor_map in targets.values():
             n_structures = (
@@ -35,8 +38,10 @@ def __len__(self):
     def __getitem__(self, index):
         """
         Generates one sample of data.
+
         Args:
             index: The index of the item in the dataset.
+
         Returns:
             A tuple containing the structure and targets for the given index.
         """
@@ -59,9 +64,11 @@ def __getitem__(self, index):
 def collate_fn(batch):
     """
     Creates a batch from a list of samples.
+
     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"""

tox.ini

@@ -64,6 +64,14 @@ commands =
     twine check dist/*.tar.gz dist/*.whl
     check-manifest {toxinidir}
 
+[testenv:docs]
+# this environement builds the documentation with sphinx
+deps =
+    -r docs/requirements.txt
+
+commands =
+    sphinx-build {posargs:-E} -W -b html docs/src docs/build/html
+
 [flake8]
 # longer lines for compatibility with other linters
 max_line_length = 88