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