From 9b5490abc9f75a8c99669fd622fd8201e94bb21e Mon Sep 17 00:00:00 2001
From: Andrea Maiani <andreamaiani@gmail.com>
Date: Fri, 5 Dec 2025 10:08:13 +0100
Subject: [PATCH] Switch documentation to Sphinx

---
 README.md             | 10 ++++++++++
 docs/api.rst          | 10 ++++++++++
 docs/conf.py          | 28 ++++++++++++++++++++++++++++
 docs/generate_docs.py | 33 +++++++++++++++++++++++++++++++++
 docs/index.rst        | 11 +++++++++++
 docs/requirements.txt |  1 +
 setup.py              |  5 ++++-
 7 files changed, 97 insertions(+), 1 deletion(-)
 create mode 100644 docs/api.rst
 create mode 100644 docs/conf.py
 create mode 100644 docs/generate_docs.py
 create mode 100644 docs/index.rst
 create mode 100644 docs/requirements.txt

diff --git a/README.md b/README.md
index 5709cb5..01d285d 100644
--- a/README.md
+++ b/README.md
@@ -26,6 +26,16 @@ To install pyUsadel, run the following command:
 ## Usage
 To use pyUsadel, simply import the library in your Python script and you can access the functions and classes provided by pyUsadel to build and run your simulations. Some example simulations are included in under the folder `doc/examples/.`
 
+## Generating documentation
+Documentation is built with [Sphinx](https://www.sphinx-doc.org/). Install the optional documentation dependency and run the generator from the repository root:
+
+```
+pip install -r docs/requirements.txt
+python docs/generate_docs.py
+```
+
+The resulting HTML files are written to `docs/_build/html/`.
+
 ## Current limitations
  - Only magnetization in the x-y plane is supported.
  - No orbital effects.
diff --git a/docs/api.rst b/docs/api.rst
new file mode 100644
index 0000000..47fedc8
--- /dev/null
+++ b/docs/api.rst
@@ -0,0 +1,10 @@
+API reference
+=============
+
+The modules listed below are documented automatically using
+``autodoc``.
+
+.. automodule:: pyusadel
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/conf.py b/docs/conf.py
new file mode 100644
index 0000000..a0ed453
--- /dev/null
+++ b/docs/conf.py
@@ -0,0 +1,28 @@
+"""Configuration for Sphinx documentation."""
+from __future__ import annotations
+
+import sys
+from datetime import datetime
+from pathlib import Path
+
+# Add project root to sys.path so autodoc can import the package
+PROJECT_ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(PROJECT_ROOT))
+
+project = "pyUsadel"
+author = "Andrea Maiani"
+
+current_year = datetime.now().year
+copyright = f"{current_year}, {author}"
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.autosummary",
+]
+
+autosummary_generate = True
+
+html_theme = "alabaster"
+
+html_static_path: list[str] = []
diff --git a/docs/generate_docs.py b/docs/generate_docs.py
new file mode 100644
index 0000000..cb56945
--- /dev/null
+++ b/docs/generate_docs.py
@@ -0,0 +1,33 @@
+"""
+Utility script to build HTML API documentation with Sphinx.
+
+Install the optional documentation dependencies first (see README instructions)
+and then run this file from the repository root::
+
+    python docs/generate_docs.py
+
+The generated site ends up in ``docs/_build/html``.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from sphinx.cmd.build import main as sphinx_main
+
+
+def main() -> None:
+    repo_root = Path(__file__).resolve().parent.parent
+    docs_dir = repo_root / "docs"
+    html_dir = docs_dir / "_build" / "html"
+    html_dir.mkdir(parents=True, exist_ok=True)
+
+    status = sphinx_main(["-b", "html", str(docs_dir), str(html_dir)])
+    if status != 0:
+        sys.exit(status)
+
+    print(f"Documentation generated in {html_dir}")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644
index 0000000..727aa86
--- /dev/null
+++ b/docs/index.rst
@@ -0,0 +1,11 @@
+pyUsadel documentation
+======================
+
+Welcome to the pyUsadel documentation. Use the table of contents below to
+navigate the available guides and API reference.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents
+
+   api
diff --git a/docs/requirements.txt b/docs/requirements.txt
new file mode 100644
index 0000000..7d7263c
--- /dev/null
+++ b/docs/requirements.txt
@@ -0,0 +1 @@
+sphinx>=7.0
diff --git a/setup.py b/setup.py
index ea2d5fe..c50470f 100644
--- a/setup.py
+++ b/setup.py
@@ -16,5 +16,8 @@
     license="MIT",
     python_requires=">=3.9",
     install_requires=["numpy>=1.21", "scipy>=1.7"],
-    extras_require={"extra": ["numba>=0.56"]},
+    extras_require={
+        "extra": ["numba>=0.56"],
+        "docs": ["sphinx>=7.0"],
+    },
 )