From 11046b6f79a64dd6a08882745eb042aad8fa39e7 Mon Sep 17 00:00:00 2001 From: Brian Ward Date: Tue, 17 Oct 2023 09:58:26 -0400 Subject: [PATCH 1/6] Start documentation --- .github/workflows/docs.yml | 67 ++++++++++++++++++++++++++++++++++ docs/Makefile | 20 ++++++++++ docs/api.rst | 8 ++++ docs/conf.py | 75 ++++++++++++++++++++++++++++++++++++++ docs/examples.rst | 6 +++ docs/index.rst | 22 +++++++++++ docs/installation.rst | 34 +++++++++++++++++ docs/make.bat | 35 ++++++++++++++++++ docs/requirements.txt | 5 +++ 9 files changed, 272 insertions(+) create mode 100644 .github/workflows/docs.yml create mode 100644 docs/Makefile create mode 100644 docs/api.rst create mode 100644 docs/conf.py create mode 100644 docs/examples.rst create mode 100644 docs/index.rst create mode 100644 docs/installation.rst create mode 100644 docs/make.bat create mode 100644 docs/requirements.txt diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..5d9354e --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,67 @@ +name: Build Pytorch-FINUFFT docs + +on: + push: + branches: + - 'main' + workflow_dispatch: + +jobs: + build-docs: + runs-on: ubuntu-latest + env: + GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} + steps: + - name: Check out github + uses: actions/checkout@v4 + with: + submodules: recursive + + - name: Set up Python 3.9 + uses: actions/setup-python@v4 + with: + python-version: 3.9 + + - name: Install dependencies (python) + run: | + python -m pip install --upgrade pip wheel + python -m pip install --upgrade -r docs/requirements.txt + + - name: Install package + run: | + pip install . + + - name: Build docs + run: | + cd docs/ + make clean + make html + + - name: Check out github + uses: actions/checkout@v4 + with: + path: docs/_build/pyt-fnft-docs + ref: gh-pages + + - name: Commit html docs + run: | + cd docs/_build/ + + ls + + rm -rf pyt-fnft-docs/* + cp -r html pyt-fnft-docs/ + + cd pyt-fnft-docs/ + git config --local user.email "41898282+github-actions[bot]@users.noreply.github.com" + git config --local user.name "github-actions[bot]" + + git add . + git commit --amend -m "Rebuild docs" + + - name: Push changes + uses: ad-m/github-push-action@master + with: + branch: gh-pages + directory: docs/_build/pyt-fnft-docs + force: true diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d4bb2cb --- /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 = . +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/api.rst b/docs/api.rst new file mode 100644 index 0000000..c1d1601 --- /dev/null +++ b/docs/api.rst @@ -0,0 +1,8 @@ +.. py:currentmodule:: Pytorch-FINUFFT + +API Reference +============= + +.. autofunction:: pytorch_finufft.functional.finufft_type1 + +.. autofunction:: pytorch_finufft.functional.finufft_type2 diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..2ef070b --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,75 @@ +# 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 datetime + +project = "Pytorch-FINUFFT" +copyright = f"{datetime.date.today().year}, Simons Foundation" +author = "Brian Ward, Michael Eickenberg" + + +extensions = [ + "sphinx.ext.autosummary", + "sphinx.ext.doctest", + "sphinx.ext.intersphinx", + "sphinx.ext.viewcode", + "sphinx.ext.napoleon", + "sphinx.ext.autodoc", + "sphinx.ext.githubpages", + "sphinx.ext.mathjax", + "nbsphinx", + "sphinx_copybutton", +] + +templates_path = ["_templates"] +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] + + +# theme options +html_theme = "pydata_sphinx_theme" +html_static_path = ["_static"] +html_show_sphinx = False + +html_theme_options = { + "icon_links": [ + { + "name": "GitHub", + "url": "https://github.com/flatironinstitute/pytorch-finufft", + "icon": "fab fa-github", + }, + ], + "use_edit_page_button": True, + "navbar_end": [ + "theme-switcher", + "navbar-icon-links", + ], +} + +html_context = { + "github_user": "flatironinstitute", + "github_repo": "pytorch-finufft", + "github_version": "main", + "doc_path": "docs", +} + + +autodoc_typehints = "signature" +napoleon_numpy_docstring = True + +# these let us auto-generate links to related projects +intersphinx_mapping = { + "python": ( + "https://docs.python.org/3/", + None, + ), + "numpy": ("https://numpy.org/doc/stable/", None), + "torch": ("https://pytorch.org/docs/master/", None), + "finufft": ("https://finufft.readthedocs.io/en/latest/", None), +} + + +# Makes the copying behavior on code examples cleaner +# by removing things like In [10]: from the text to be copied +copybutton_prompt_text = r">>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: " +copybutton_prompt_is_regexp = True diff --git a/docs/examples.rst b/docs/examples.rst new file mode 100644 index 0000000..8dd0632 --- /dev/null +++ b/docs/examples.rst @@ -0,0 +1,6 @@ + +Examples +======== + + +This page is currently unpopulated. diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..0dc2f05 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,22 @@ +.. Pytorch-FINUFFT documentation master file, created by + sphinx-quickstart on Tue Oct 17 09:24:06 2023. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Pytorch-FINUFFT +=============== + +This package provides a `Pytorch `_ interface to the +`Flatiron Instutute Non-uniform FFT (FINUFFT) `_ +library. + +Currently, this supports both forward evaluation and backward differentiation in +both values and positions for the `"type 1" and "type 2" `_ transforms. + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + installation + examples + api diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 index 0000000..7df5596 --- /dev/null +++ b/docs/installation.rst @@ -0,0 +1,34 @@ +Installation +============ + + +Pre-requistes +------------- + +Pytorch-FINUFFT requires either ``finufft`` *and/or* ``cufinufft`` +2.2.0 or greater. Currently, this version is unreleased +and can only be installed from source. See the relevant pages for +`finufft `_ +and +`cufinufft `_. + + +Pytorch-FINUFFT also requires ``pytorch`` 2.0 or greater. See the installation +matrix on `Pytorch's website `_. + + +Source Installation +------------------- + +Once the pre-requisites are installed, you can install Pytorch-FINUFFT +from source by running + +.. code-block:: bash + + pip install -U git+https://github.com/flatironinstitute/pytorch-finufft.git + + +Installation from PyPI +---------------------- + +TBD. diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..954237b --- /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/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..7f01219 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,5 @@ +sphinx +nbsphinx +sphinx_copybutton +sphinx-gallery +pydata-sphinx-theme From 743acedcc5741eea04b5a691b14300f516bfff70 Mon Sep 17 00:00:00 2001 From: Brian Ward Date: Tue, 17 Oct 2023 15:45:31 -0400 Subject: [PATCH 2/6] Link to finufft with intersphinx instead --- docs/installation.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/installation.rst b/docs/installation.rst index 7df5596..28ee2ef 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -8,9 +8,8 @@ Pre-requistes Pytorch-FINUFFT requires either ``finufft`` *and/or* ``cufinufft`` 2.2.0 or greater. Currently, this version is unreleased and can only be installed from source. See the relevant pages for -`finufft `_ -and -`cufinufft `_. +:external+finufft:doc:`finufft ` and +:external+finufft:doc:`cufinufft `. Pytorch-FINUFFT also requires ``pytorch`` 2.0 or greater. See the installation From ed25ac462d616d6892325615dd18783bd53bd9b9 Mon Sep 17 00:00:00 2001 From: Brian Ward Date: Tue, 17 Oct 2023 15:48:20 -0400 Subject: [PATCH 3/6] Allow docs to build without torch, finufft installed --- docs/conf.py | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/conf.py b/docs/conf.py index 2ef070b..3d0742c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -54,6 +54,7 @@ } +autodoc_mock_imports = ["torch", "finufft", "cufinufft"] autodoc_typehints = "signature" napoleon_numpy_docstring = True From d4313a6b38720376fb7d0a29405546b44c28fd4e Mon Sep 17 00:00:00 2001 From: Brian Ward Date: Tue, 17 Oct 2023 15:52:57 -0400 Subject: [PATCH 4/6] Link to finufft with intersphinx instead --- docs/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.rst b/docs/index.rst index 0dc2f05..03c1e34 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -11,7 +11,7 @@ This package provides a `Pytorch `_ interface to the library. Currently, this supports both forward evaluation and backward differentiation in -both values and positions for the `"type 1" and "type 2" `_ transforms. +both values and positions for the :external+finufft:doc:`"type 1" and "type 2" ` transforms. .. toctree:: :maxdepth: 2 From 30290723325d0c36a54e67be8fa2fe1c4f771927 Mon Sep 17 00:00:00 2001 From: Brian Ward Date: Tue, 17 Oct 2023 16:46:17 -0400 Subject: [PATCH 5/6] Add texext, CI to check doc before merge --- .github/workflows/main.yml | 24 ++++++++++++++++++++++++ docs/conf.py | 1 + docs/requirements.txt | 1 + 3 files changed, 26 insertions(+) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 8983ba5..c805840 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -65,3 +65,27 @@ jobs: - name: Lint with mypy run: | mypy pytorch_finufft/ + + + doc-check: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - name: Set up Python + uses: actions/setup-python@v4.6.1 + with: + python-version: "3.11" + + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install -r docs/requirements.txt + pip install -e . + + - name: Check docs + env: + SPHINXOPTS: "-Wq --keep-going" + run: | + cd docs/ + make clean + make linkcheck diff --git a/docs/conf.py b/docs/conf.py index 3d0742c..6a8a99c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -20,6 +20,7 @@ "sphinx.ext.mathjax", "nbsphinx", "sphinx_copybutton", + "texext.math_dollar", ] templates_path = ["_templates"] diff --git a/docs/requirements.txt b/docs/requirements.txt index 7f01219..06c013f 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -3,3 +3,4 @@ nbsphinx sphinx_copybutton sphinx-gallery pydata-sphinx-theme +texext From 991a63bdffcb19d6eb1a60aca99f4e98544a54bb Mon Sep 17 00:00:00 2001 From: Brian Ward Date: Tue, 17 Oct 2023 16:50:51 -0400 Subject: [PATCH 6/6] Update CI config --- .github/workflows/docs.yml | 7 ++----- .github/workflows/main.yml | 8 ++++---- docs/conf.py | 2 +- 3 files changed, 7 insertions(+), 10 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 5d9354e..c298e29 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -22,14 +22,11 @@ jobs: with: python-version: 3.9 - - name: Install dependencies (python) + - name: Install dependencies and package run: | python -m pip install --upgrade pip wheel python -m pip install --upgrade -r docs/requirements.txt - - - name: Install package - run: | - pip install . + python -m pip install --no-deps . - name: Build docs run: | diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index c805840..fdc3ce2 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -29,7 +29,7 @@ jobs: - name: Install dependencies run: | python -m pip install --upgrade pip - pip install .[dev] + python -m pip install .[dev] - name: Pytest run: | @@ -48,7 +48,7 @@ jobs: - name: Install dependencies run: | python -m pip install --upgrade pip - pip install -e .[dev] + python -m pip install -e .[dev] - name: Check formatting run: | @@ -79,8 +79,8 @@ jobs: - name: Install dependencies run: | python -m pip install --upgrade pip - pip install -r docs/requirements.txt - pip install -e . + python -m pip install -r docs/requirements.txt + python -m pip install --no-deps -e . - name: Check docs env: diff --git a/docs/conf.py b/docs/conf.py index 6a8a99c..14e7b24 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -29,7 +29,7 @@ # theme options html_theme = "pydata_sphinx_theme" -html_static_path = ["_static"] +# html_static_path = ["_static"] html_show_sphinx = False html_theme_options = {