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 index 75b803b..2ab411b 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -34,16 +34,17 @@ jobs: run: | pip install -e . - # ADJUST THIS: build your documentation into docs/. - # We use a custom build script for pdoc itself, ideally you just run `pdoc -o docs/ ...` here. - - name: Build Docs + - name: Install sphinx run: | - mkdir -p ./docs - python -m pdoc --docformat numpy --logo "https://avatars.githubusercontent.com/u/88346553?s=200&v=4" mantra -o ./docs + 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/ + path: docs/build # Deploy the artifact to GitHub pages. # This is a separate job so that only actions/deploy-pages has the necessary permissions. @@ -58,4 +59,4 @@ jobs: url: ${{ steps.deployment.outputs.page_url }} steps: - id: deployment - uses: actions/deploy-pages@v4 \ No newline at end of file + uses: actions/deploy-pages@v4 diff --git a/.gitignore b/.gitignore index b3dbe4e..d7ba39a 100644 --- a/.gitignore +++ b/.gitignore @@ -6,4 +6,6 @@ bu/ test_* **/__pycache__ **/*.egg-info -processed/** \ No newline at end of file +processed/** + +docs/build diff --git a/README.md b/README.md index 62de7c0..efc4731 100644 --- a/README.md +++ b/README.md @@ -17,9 +17,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 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..cf53c05 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,44 @@ +# 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', +] + +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 = 'alabaster' +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/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,