diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 29cb682..2185ae8 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -14,7 +14,6 @@ permissions: env: UV_VERSION: "0.8" - UV_LINK_MODE: "copy" jobs: build: diff --git a/.github/workflows/sphinx.yml b/.github/workflows/sphinx.yml new file mode 100644 index 0000000..cc02683 --- /dev/null +++ b/.github/workflows/sphinx.yml @@ -0,0 +1,43 @@ +name: "Sphinx: Render docs" + +on: + push: + branches: [ "main" ] + pull_request: + branches: [ "main" ] + +env: + UV_VERSION: "0.8" + +jobs: + build: + runs-on: ubuntu-latest + permissions: + contents: write + steps: + - uses: actions/checkout@v4 + with: + persist-credentials: false + - name: Build HTML + uses: ammaraskar/sphinx-action@master + with: + docs-folder: docs + build-command: make html + pre-build-command: | + python -m pip install -U pip + python -m pip install "uv==${{ env.UV_VERSION }}" + uv --version + uv venv + uv pip install -e ".[docs]" + df -h + - name: Upload artifacts + uses: actions/upload-artifact@v4 + with: + name: html-docs + path: docs/source/build/html/ + - name: Deploy + uses: peaceiris/actions-gh-pages@v3 + if: github.ref == 'refs/heads/main' + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: docs/source/build/html diff --git a/.gitignore b/.gitignore index af97abc..068ca00 100644 --- a/.gitignore +++ b/.gitignore @@ -4,3 +4,16 @@ dist/* .DS_Store __pycache__/ *.pyc + +models/ + +# Sphinx build artifacts +docs/_build/ +docs/build/ +docs/source/_build/ +docs/source/build/ + +# Autosummary/autogenerated pages +docs/source/_autosummary/ +docs/source/_generated/ +docs/source/_api/ diff --git a/README.md b/README.md index 580b0ae..3dc5045 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ Batched optimisation algorithms for neural network potential–driven molecular - IO methods for RDkit molecules and ASE atoms objects. ## Installation -Pre-requisities: Python 3.11, PyTorch and PyTorch Geometric compatible with your envirnment +Pre-requisities: Python 3.11, PyTorch and PyTorch Geometric compatible with your environment. ```bash # For example @@ -136,9 +136,7 @@ class MyCalculator(Calculator): return energies, forces def to_atomic_data(): - pass - - def from_atomic_data(): + # writing this in a batched format is crucial for GPU acceleration pass ``` diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..b881cfe --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SOURCEDIR = source +BUILDDIR = source/_build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..8f56beb --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/source/_static/.gitkeep b/docs/source/_static/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/docs/source/_templates/.gitkeep b/docs/source/_templates/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/docs/source/api.rst b/docs/source/api.rst new file mode 100644 index 0000000..5467528 --- /dev/null +++ b/docs/source/api.rst @@ -0,0 +1,12 @@ +.. rst + +API reference +============= + +The public API is documented below. Expand entries to see available classes and functions. + +.. autosummary:: + :toctree: _autosummary + :recursive: + + neural_optimiser diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..bb7b7b1 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,99 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +import os +import sys +from datetime import date + +# Make the src/ directory importable so autodoc can find neural_optimiser +sys.path.insert(0, os.path.abspath("../../src")) + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = "neural-optimiser" +author = "Ewan Wallace" +copyright = f"{date.today().year}, {author}" + +# Dynamic versioning +release = "0.0.0" +try: + from importlib.metadata import PackageNotFoundError, version # py3.8+ + + try: + release = version("neural-optimiser") + except PackageNotFoundError: + try: + from neural_optimiser import __version__ # noqa: F401 + + release = __version__ + except Exception: + pass +except Exception: + pass + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.autosummary", + "sphinx.ext.napoleon", + "sphinx.ext.viewcode", + "sphinx.ext.intersphinx", + "sphinx.ext.extlinks", + "myst_parser", +] + +extlinks = { + "pyg": ("https://pytorch-geometric.readthedocs.io/en/latest/generated/%s.html", "%s"), +} + +# Support .rst and .md sources +source_suffix = { + ".rst": "restructuredtext", + ".md": "markdown", +} + +templates_path = ["_templates"] +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = "furo" +html_static_path = ["_static"] + +# Autodoc/autosummary +autosummary_generate = True +autodoc_default_options = { + "members": True, + "undoc-members": True, + "inherited-members": True, + "show-inheritance": True, +} +autodoc_typehints = "description" + +# Napoleon (Google/Numpy style docstrings) +napoleon_google_docstring = True +napoleon_numpy_docstring = True +napoleon_attr_annotations = True + +# Intersphinx links +intersphinx_mapping = { + "python": ("https://docs.python.org/3", {}), + "numpy": ("https://numpy.org/doc/stable/", {}), + "torch": ("https://pytorch.org/docs/stable/", {}), +} + +# MyST config +myst_enable_extensions = [ + "colon_fence", + "deflist", + "fieldlist", + "html_admonition", + "html_image", + "tasklist", +] diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..6096151 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,20 @@ +.. neural-optimiser documentation master file, created by + sphinx-quickstart on Thu Oct 23 06:10:35 2025. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +neural-optimiser documentation +============================== + +Overview +-------- + +.. mdinclude:: ../../README.md + +Contents +-------- + +.. toctree:: + :maxdepth: 2 + + api diff --git a/pyproject.toml b/pyproject.toml index 8b25bfc..08770a0 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -19,6 +19,7 @@ dependencies = [ "numpy", "loguru", "universal-pathlib", + "sphinx", ] [project.optional-dependencies] @@ -27,6 +28,13 @@ dev = [ "pre-commit", ] +docs = [ + "sphinx>=3.0.0", + "furo==2021.11.16", + "myst-parser", + "sphinx-autodoc-typehints" +] + [tool.uv.sources] torch = { index = "pytorch-cu128" } torch-cluster = { index = "pyg-cu128" }