Switch documentation generation to Sphinx

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.

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:

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] = []

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()

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

docs/requirements.txt

@@ -0,0 +1 @@
+sphinx>=7.0

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"],
+    },
 )