From 623bc8ab005ce858dd2400bf089e2d744b38da37 Mon Sep 17 00:00:00 2001
From: Andrea Maiani <andreamaiani@gmail.com>
Date: Fri, 5 Dec 2025 10:22:23 +0100
Subject: [PATCH] Add helper for generating docs with pdoc

---
 README.md             | 10 ++++++++++
 docs/generate_docs.py | 37 +++++++++++++++++++++++++++++++++++++
 docs/requirements.txt |  1 +
 setup.py              |  5 ++++-
 4 files changed, 52 insertions(+), 1 deletion(-)
 create mode 100644 docs/generate_docs.py
 create mode 100644 docs/requirements.txt

diff --git a/README.md b/README.md
index 5709cb5..53c13a6 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
+The repository includes a helper script for building API documentation with [pdoc](https://pdoc.dev/). 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/site/`.
+
 ## Current limitations
  - Only magnetization in the x-y plane is supported.
  - No orbital effects.
diff --git a/docs/generate_docs.py b/docs/generate_docs.py
new file mode 100644
index 0000000..348bf50
--- /dev/null
+++ b/docs/generate_docs.py
@@ -0,0 +1,37 @@
+"""
+Utility script to build HTML API documentation with pdoc.
+
+The script installs no dependencies on its own; install the optional
+``pdoc`` package 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/site``.
+"""
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+
+def main() -> None:
+    repo_root = Path(__file__).resolve().parent.parent
+    output_dir = repo_root / "docs" / "site"
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    cmd = [
+        sys.executable,
+        "-m",
+        "pdoc",
+        "pyusadel",
+        "-o",
+        str(output_dir),
+    ]
+    subprocess.check_call(cmd, cwd=repo_root)
+    print(f"Documentation generated in {output_dir}")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/docs/requirements.txt b/docs/requirements.txt
new file mode 100644
index 0000000..800633d
--- /dev/null
+++ b/docs/requirements.txt
@@ -0,0 +1 @@
+pdoc>=14.0.0
diff --git a/setup.py b/setup.py
index ea2d5fe..9c77399 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": ["pdoc>=14.0.0"],
+    },
 )