From 6a6ad147cc07d7f0ab875ff4c9169c31ed22ddd8 Mon Sep 17 00:00:00 2001
From: Guillaume Fraux <guillaume.fraux@epfl.ch>
Date: Wed, 17 Jul 2024 14:58:05 +0200
Subject: [PATCH] Add documentation using sphinx

---
 .gitignore             |  1 +
 docs/src/conf.py       | 36 ++++++++++++++++++++++++++++++++++++
 docs/src/index.rst     |  8 ++++++++
 docs/src/reference.rst |  5 +++++
 tox.ini                |  8 ++++++++
 5 files changed, 58 insertions(+)
 create mode 100644 docs/src/conf.py
 create mode 100644 docs/src/index.rst
 create mode 100644 docs/src/reference.rst

diff --git a/.gitignore b/.gitignore
index 7e46760..6c919d7 100644
--- a/.gitignore
+++ b/.gitignore
@@ -3,3 +3,4 @@ dist/
 *.pyc
 __pycache__/
 *.egg-info/
+.tox/
diff --git a/docs/src/conf.py b/docs/src/conf.py
new file mode 100644
index 0000000..6ce627a
--- /dev/null
+++ b/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),
+}
diff --git a/docs/src/index.rst b/docs/src/index.rst
new file mode 100644
index 0000000..6bcb983
--- /dev/null
+++ b/docs/src/index.rst
@@ -0,0 +1,8 @@
+ShiftML documentation
+=====================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   reference
diff --git a/docs/src/reference.rst b/docs/src/reference.rst
new file mode 100644
index 0000000..3e882d6
--- /dev/null
+++ b/docs/src/reference.rst
@@ -0,0 +1,5 @@
+API reference
+=============
+
+.. automodule:: shiftml
+    :members:
diff --git a/tox.ini b/tox.ini
index c8ddb5a..1a65f33 100644
--- a/tox.ini
+++ b/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