From c548c50d476e9df3c293bae29ea414c1ecc85b83 Mon Sep 17 00:00:00 2001 From: Philip Loche Date: Tue, 5 Dec 2023 09:20:02 +0100 Subject: [PATCH] more structure to utils docs --- .readthedocs.yml | 21 +++--- docs/requirements.txt | 9 +-- docs/src/conf.py | 69 ++++++++++++------- docs/src/{dev-docs.rst => dev-docs/index.rst} | 4 +- docs/src/dev-docs/utils-api.rst | 13 ---- docs/src/dev-docs/utils/dataset.rst | 7 ++ docs/src/dev-docs/utils/index.rst | 10 +++ docs/src/dev-docs/utils/readers/index.rst | 17 +++++ docs/src/dev-docs/utils/readers/structure.rst | 13 ++++ docs/src/dev-docs/utils/readers/target.rst | 13 ++++ docs/src/index.rst | 2 +- pyproject.toml | 4 +- src/metatensor_models/utils/data/dataset.py | 4 +- .../utils/data/readers/structures/__init__.py | 1 + .../utils/data/readers/targets/__init__.py | 1 + 15 files changed, 127 insertions(+), 61 deletions(-) rename docs/src/{dev-docs.rst => dev-docs/index.rst} (84%) delete mode 100644 docs/src/dev-docs/utils-api.rst create mode 100644 docs/src/dev-docs/utils/dataset.rst create mode 100644 docs/src/dev-docs/utils/index.rst create mode 100644 docs/src/dev-docs/utils/readers/index.rst create mode 100644 docs/src/dev-docs/utils/readers/structure.rst create mode 100644 docs/src/dev-docs/utils/readers/target.rst diff --git a/.readthedocs.yml b/.readthedocs.yml index 99c79e735..5f1a45c3e 100644 --- a/.readthedocs.yml +++ b/.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 diff --git a/docs/requirements.txt b/docs/requirements.txt index 9d190fe45..2b9fe95fc 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,4 +1,5 @@ -sphinx >= 4.0.0 # documentation generator -sphinx-toggleprompt # hide the prompt (>>>) in python doctests -pygments >=2.11 # syntax highligthing -sphinx_rtd_dark_mode # sphinx theme +furo +sphinx >= 7 +sphinx-toggleprompt +tomli + diff --git a/docs/src/conf.py b/docs/src/conf.py index 1e9c24ffd..a2cdc927c 100644 --- a/docs/src/conf.py +++ b/docs/src/conf.py @@ -1,43 +1,45 @@ -# 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" @@ -45,13 +47,34 @@ 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", +] diff --git a/docs/src/dev-docs.rst b/docs/src/dev-docs/index.rst similarity index 84% rename from docs/src/dev-docs.rst rename to docs/src/dev-docs/index.rst index a970ed38d..6b38b800c 100644 --- a/docs/src/dev-docs.rst +++ b/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 diff --git a/docs/src/dev-docs/utils-api.rst b/docs/src/dev-docs/utils-api.rst deleted file mode 100644 index cea1cacb0..000000000 --- a/docs/src/dev-docs/utils-api.rst +++ /dev/null @@ -1,13 +0,0 @@ -Utils API -========= - -This is the API for the ``utils`` module of ``metatensor-models``. - -.. automodule:: metatensor_models.utils.data - :members: - -.. automodule:: metatensor_models.utils.data.dataset - :members: - -.. automodule:: metatensor_models.utils.data.readers - :members: 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/index.rst b/docs/src/index.rst index 13b3b27b7..500d2eae7 100644 --- a/docs/src/index.rst +++ b/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 diff --git a/pyproject.toml b/pyproject.toml index b39804491..e898faefb 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 16cccb6a8..4f76a9354 100644 --- a/src/metatensor_models/utils/data/dataset.py +++ b/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. """ 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"""