diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 000000000..d0dfdefdb --- /dev/null +++ b/.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 diff --git a/.github/workflows/pr-docs-preview.yml b/.github/workflows/pr-docs-preview.yml new file mode 100644 index 000000000..f006c2572 --- /dev/null +++ b/.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 diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 000000000..eaffa2220 --- /dev/null +++ b/.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 diff --git a/MANIFEST.in b/MANIFEST.in index c373117d0..35a45f68b 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -10,5 +10,6 @@ prune .tox exclude .gitignore exclude tox.ini +exclude .readthedocs.yml global-exclude *.py[cod] __pycache__/* *.so *.dylib diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 000000000..ec83730ea --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,4 @@ +furo +sphinx >= 7 +sphinx-toggleprompt +tomli diff --git a/docs/src/_static/.gitkeep b/docs/src/_static/.gitkeep new file mode 100644 index 000000000..e69de29bb diff --git a/docs/src/_templates/.gitkeep b/docs/src/_templates/.gitkeep new file mode 100644 index 000000000..e69de29bb diff --git a/docs/src/conf.py b/docs/src/conf.py new file mode 100644 index 000000000..f4958dd77 --- /dev/null +++ b/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", +] diff --git a/docs/src/dev-docs/adding-models.rst b/docs/src/dev-docs/adding-models.rst new file mode 100644 index 000000000..a97544db4 --- /dev/null +++ b/docs/src/dev-docs/adding-models.rst @@ -0,0 +1,4 @@ +Adding new models +================= + +To be done. diff --git a/docs/src/dev-docs/index.rst b/docs/src/dev-docs/index.rst new file mode 100644 index 000000000..6b38b800c --- /dev/null +++ b/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 diff --git a/docs/src/dev-docs/utils/dataset.rst b/docs/src/dev-docs/utils/dataset.rst new file mode 100644 index 000000000..f1642129c --- /dev/null +++ b/docs/src/dev-docs/utils/dataset.rst @@ -0,0 +1,7 @@ +Dataset +####### + +.. automodule:: metatensor_models.utils.data.dataset + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/src/dev-docs/utils/index.rst b/docs/src/dev-docs/utils/index.rst new file mode 100644 index 000000000..e01d3bbc4 --- /dev/null +++ b/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 diff --git a/docs/src/dev-docs/utils/readers/index.rst b/docs/src/dev-docs/utils/readers/index.rst new file mode 100644 index 000000000..19ee22c83 --- /dev/null +++ b/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 diff --git a/docs/src/dev-docs/utils/readers/structure.rst b/docs/src/dev-docs/utils/readers/structure.rst new file mode 100644 index 000000000..fca290ae4 --- /dev/null +++ b/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 diff --git a/docs/src/dev-docs/utils/readers/target.rst b/docs/src/dev-docs/utils/readers/target.rst new file mode 100644 index 000000000..4b2401427 --- /dev/null +++ b/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 diff --git a/docs/src/how-to.rst b/docs/src/how-to.rst new file mode 100644 index 000000000..40c7ebf47 --- /dev/null +++ b/docs/src/how-to.rst @@ -0,0 +1,4 @@ +How-to +====== + +This section describes how to use the ``metatensor-models`` package. diff --git a/docs/src/index.rst b/docs/src/index.rst new file mode 100644 index 000000000..500d2eae7 --- /dev/null +++ b/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 diff --git a/docs/src/models.rst b/docs/src/models.rst new file mode 100644 index 000000000..552ced480 --- /dev/null +++ b/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/* diff --git a/docs/src/models/soap-bpnn.rst b/docs/src/models/soap-bpnn.rst new file mode 100644 index 000000000..d47264022 --- /dev/null +++ b/docs/src/models/soap-bpnn.rst @@ -0,0 +1,4 @@ +SOAP-BPNN +========= + +This is a Behler-Parrinello neural network with SOAP features. diff --git a/docs/src/quickstart.rst b/docs/src/quickstart.rst new file mode 100644 index 000000000..bd310ba66 --- /dev/null +++ b/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 diff --git a/pyproject.toml b/pyproject.toml index 1ccea6e4a..be063013c 100644 --- a/pyproject.toml +++ b/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", diff --git a/src/metatensor_models/utils/data/dataset.py b/src/metatensor_models/utils/data/dataset.py index f94754a08..4f76a9354 100644 --- a/src/metatensor_models/utils/data/dataset.py +++ b/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. """ diff --git a/src/metatensor_models/utils/data/readers/structures/__init__.py b/src/metatensor_models/utils/data/readers/structures/__init__.py index 123a893df..ca8eeb2fb 100644 --- a/src/metatensor_models/utils/data/readers/structures/__init__.py +++ b/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""" diff --git a/src/metatensor_models/utils/data/readers/targets/__init__.py b/src/metatensor_models/utils/data/readers/targets/__init__.py index 69a98d1a8..ba5168f79 100644 --- a/src/metatensor_models/utils/data/readers/targets/__init__.py +++ b/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""" diff --git a/tox.ini b/tox.ini index 3afeb3976..e2c96f475 100644 --- a/tox.ini +++ b/tox.ini @@ -75,6 +75,14 @@ allowlist_externals = commands = pytest --import-mode=append {posargs} src/metatensor_models/soap_bpnn/tests/ +[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