Add documentation using sphinx

.gitignore

@@ -3,3 +3,4 @@ dist/
 *.pyc
 __pycache__/
 *.egg-info/
+.tox/

docs/src/conf.py

@@ -0,0 +1,36 @@
+import os
+
+os.environ["METATENSOR_IMPORT_FOR_SPHINX"] = "1"
+
+import shiftml  # noqa: E402
+
+project = "ShiftML"
+copyright = "2024, ShiftML developers"
+author = "TODO"
+release = shiftml.__version__
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
+]
+
+exclude_patterns = []
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "alabaster"
+
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+    "torch": ("https://pytorch.org/docs/stable/", None),
+    "rascaline": ("https://luthaf.fr/rascaline/latest/", None),
+    "metatensor": ("https://docs.metatensor.org/latest/", None),
+    "ase": ("https://wiki.fysik.dtu.dk/ase/", None),
+}

docs/src/index.rst

@@ -0,0 +1,8 @@
+ShiftML documentation
+=====================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   reference

docs/src/reference.rst

@@ -0,0 +1,5 @@
+API reference
+=============
+
+.. automodule:: shiftml
+    :members:

tox.ini

@@ -46,6 +46,14 @@ commands =
     isort src tests
 
 
+[testenv:docs]
+description = Invoke sphinx-build to build the HTML docs
+deps =
+    sphinx
+commands =
+    sphinx-build -d docs/build/doctrees -W -b html docs/src docs/build/html
+
+
 [flake8]
 max_line_length = 88
 extend-ignore = E203