diff --git a/.github/workflows/black.yaml b/.github/workflows/black.yaml index 9e83aba..a13ddf9 100644 --- a/.github/workflows/black.yaml +++ b/.github/workflows/black.yaml @@ -9,7 +9,7 @@ jobs: - uses: actions/checkout@v4 - uses: psf/black@stable with: - options: "--check --verbose --line-length 80" + options: "--check --verbose --line-length 80 --exclude docs/" # Ignore Jupyter notebooks for now to simplify rapid # prototyping. jupyter: false diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml new file mode 100644 index 0000000..2ab411b --- /dev/null +++ b/.github/workflows/docs.yaml @@ -0,0 +1,62 @@ +name: Build the documentation. + +# build the documentation whenever there are new commits on main +on: + push: + # Alternative: only build for tags. + tags: + - '*' + workflow_dispatch: + +# security: restrict permissions for CI jobs. +permissions: + contents: read + +jobs: + # Build the documentation and upload the static HTML files as an artifact. + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: '3.10.11' + cache: 'pip' + - name: Install dependencies + run: | + pip install torch==2.2.0 + pip install numpy + pip install git+https://github.com/Lezcano/geotorch/ + pip install pdoc + + # ADJUST THIS: install all dependencies (including pdoc) + - name: Install mantra + run: | + pip install -e . + + - name: Install sphinx + run: | + pip install sphinx sphinx_rtd_theme myst_parser + + - name: Sphinx build + run: | + sphinx-build docs/source docs/build + + - uses: actions/upload-pages-artifact@v3 + with: + path: docs/build + + # Deploy the artifact to GitHub pages. + # This is a separate job so that only actions/deploy-pages has the necessary permissions. + deploy: + needs: build + runs-on: ubuntu-latest + permissions: + pages: write + id-token: write + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - id: deployment + uses: actions/deploy-pages@v4 diff --git a/.gitignore b/.gitignore index d6619c2..08a8191 100644 --- a/.gitignore +++ b/.gitignore @@ -11,4 +11,6 @@ scratch_** /build /visualization -/tables \ No newline at end of file +/tables + +docs/build diff --git a/CNAME b/CNAME new file mode 100644 index 0000000..a44db15 --- /dev/null +++ b/CNAME @@ -0,0 +1 @@ +mantra.aidos.group diff --git a/README.md b/README.md index 72da569..cd1e6d2 100644 --- a/README.md +++ b/README.md @@ -19,9 +19,9 @@ pip install mantra-dataset After installation the dataset can be used with the follwing snippet. ```python -from mantra.simplicial import SimplicialDataset +from mantra.datasets import ManifoldTriangulations -dataset = SimplicialDataset(root="./data", manifold="2", version="latest") +dataset = ManifoldTriangulations(root="./data", manifold="2", version="latest") ``` ## Folder Structure @@ -52,7 +52,7 @@ triangulation having the following attributes: * `betti_numbers` (required, `list` of `int`): A list of the [Betti numbers](https://en.wikipedia.org/wiki/Betti_number) of the - triangulation, computed using $Z_2$ coefficients. This implies that + triangulation, computed using $Z$ coefficients. This implies that [torsion](https://en.wikipedia.org/wiki/Homology_(mathematics)) coefficients are stored in another attribute. diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d0c3cbf --- /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 = 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..747ffb7 --- /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=source +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/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..aa2b104 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,45 @@ +# 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 + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = "MANTRA" +copyright = "2024, Ernst Röell, Daniel Bin Schmid, Bastian Rieck" +author = "Ernst Röell, Daniel Bin Schmid, Bastian Rieck" + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + "sphinx.ext.autodoc", + "sphinx_rtd_theme", +] + +templates_path = ["_templates"] +exclude_patterns = ["build", "Thumbs.db", ".DS_Store"] + + +# Ensure that member functions are documented. These are sane defaults. +autodoc_default_options = { + "members": True, + "member-order": "bysource", + "special-members": "__init__", + "undoc-members": True, + "exclude-members": "__weakref__", +} + +# Tries to assign some semantic meaning to arguments provided with +# single backtics, such as `x`. This way, we can ignore `func` and +# `class` targets etc. (They still work, though!) +default_role = "obj" + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = "sphinx_rtd_theme" +html_static_path = ["_static"] + +modindex_common_prefix = ["mantra."] diff --git a/docs/source/datasets.rst b/docs/source/datasets.rst new file mode 100644 index 0000000..79d8b4c --- /dev/null +++ b/docs/source/datasets.rst @@ -0,0 +1,6 @@ +mantra.datasets +=============== + +.. automodule:: mantra.datasets + :members: + diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..643cfff --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,20 @@ + +MANTRA +====== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + +.. toctree:: + :maxdepth: 2 + :caption: Modules + + datasets + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/mantra/__init__.py b/mantra/__init__.py index e69de29..ae675c2 100644 --- a/mantra/__init__.py +++ b/mantra/__init__.py @@ -0,0 +1,3 @@ +""" +.. include:: ../README.md +""" diff --git a/mantra/simplicial.py b/mantra/datasets.py similarity index 90% rename from mantra/simplicial.py rename to mantra/datasets.py index 44bcb5e..4e602be 100644 --- a/mantra/simplicial.py +++ b/mantra/datasets.py @@ -1,7 +1,7 @@ -""" -The dataset class for the manifolds. It consists of 2 and 3 manifolds -along with the topological information. We follow the pytorch geometric -conventions for the dataset. +"""Datasets module + +This module contains datasets describing triangulations of manifolds, +following the API `pytorch-geometric`. """ import os @@ -15,7 +15,7 @@ ) -class SimplicialDataset(InMemoryDataset): +class ManifoldTriangulations(InMemoryDataset): def __init__( self,