Skip to content

Commit

Permalink
more structure to utils docs
Browse files Browse the repository at this point in the history
  • Loading branch information
PicoCentauri committed Dec 5, 2023
1 parent ded5c0d commit c548c50
Show file tree
Hide file tree
Showing 15 changed files with 127 additions and 61 deletions.
21 changes: 8 additions & 13 deletions .readthedocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
9 changes: 5 additions & 4 deletions docs/requirements.txt
Original file line number Diff line number Diff line change
@@ -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

69 changes: 46 additions & 23 deletions docs/src/conf.py
Original file line number Diff line number Diff line change
@@ -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",
]
4 changes: 2 additions & 2 deletions docs/src/dev-docs.rst → docs/src/dev-docs/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
13 changes: 0 additions & 13 deletions docs/src/dev-docs/utils-api.rst

This file was deleted.

7 changes: 7 additions & 0 deletions docs/src/dev-docs/utils/dataset.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
Dataset
#######

.. automodule:: metatensor_models.utils.data.dataset
:members:
:undoc-members:
:show-inheritance:
10 changes: 10 additions & 0 deletions docs/src/dev-docs/utils/index.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
Utilitliy API
=============

This is the API for the ``utils`` module of ``metatensor-models``.

.. toctree::
:maxdepth: 1

dataset
readers/index
17 changes: 17 additions & 0 deletions docs/src/dev-docs/utils/readers/index.rst
Original file line number Diff line number Diff line change
@@ -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
13 changes: 13 additions & 0 deletions docs/src/dev-docs/utils/readers/structure.rst
Original file line number Diff line number Diff line change
@@ -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
13 changes: 13 additions & 0 deletions docs/src/dev-docs/utils/readers/target.rst
Original file line number Diff line number Diff line change
@@ -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
2 changes: 1 addition & 1 deletion docs/src/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -9,4 +9,4 @@ This is a collection of atomistic models interfaced with ``metatensor``.
quickstart
how-to
models
dev-docs
dev-docs/index
4 changes: 1 addition & 3 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
4 changes: 2 additions & 2 deletions src/metatensor_models/utils/data/dataset.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.
"""
Expand All @@ -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.
"""
Expand Down
Original file line number Diff line number Diff line change
@@ -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"""
Original file line number Diff line number Diff line change
@@ -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"""

0 comments on commit c548c50

Please sign in to comment.