Skip to content

Commit

Permalink
Merge pull request #90 from flatironinstitute/start-docs
Browse files Browse the repository at this point in the history
Start documentation
WardBrian authored Oct 17, 2023

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
2 parents 020842c + 991a63b commit cbd664c
Showing 10 changed files with 297 additions and 2 deletions.
64 changes: 64 additions & 0 deletions .github/workflows/docs.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
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 and package
run: |
python -m pip install --upgrade pip wheel
python -m pip install --upgrade -r docs/requirements.txt
python -m pip install --no-deps .
- 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
28 changes: 26 additions & 2 deletions .github/workflows/main.yml
Original file line number Diff line number Diff line change
@@ -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: |
@@ -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/[email protected]
with:
python-version: "3.11"

- name: Install dependencies
run: |
python -m pip install --upgrade pip
python -m pip install -r docs/requirements.txt
python -m pip install --no-deps -e .
- name: Check docs
env:
SPHINXOPTS: "-Wq --keep-going"
run: |
cd docs/
make clean
make linkcheck
20 changes: 20 additions & 0 deletions docs/Makefile
Original file line number Diff line number Diff line change
@@ -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)
8 changes: 8 additions & 0 deletions docs/api.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
.. py:currentmodule:: Pytorch-FINUFFT
API Reference
=============

.. autofunction:: pytorch_finufft.functional.finufft_type1

.. autofunction:: pytorch_finufft.functional.finufft_type2
77 changes: 77 additions & 0 deletions docs/conf.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
# 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",
"texext.math_dollar",
]

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_mock_imports = ["torch", "finufft", "cufinufft"]
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
6 changes: 6 additions & 0 deletions docs/examples.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@

Examples
========


This page is currently unpopulated.
22 changes: 22 additions & 0 deletions docs/index.rst
Original file line number Diff line number Diff line change
@@ -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 <https://pytorch.org/>`_ interface to the
`Flatiron Instutute Non-uniform FFT (FINUFFT) <https://finufft.readthedocs.io/en/latest/>`_
library.

Currently, this supports both forward evaluation and backward differentiation in
both values and positions for the :external+finufft:doc:`"type 1" and "type 2" <math>` transforms.

.. toctree::
:maxdepth: 2
:caption: Contents:

installation
examples
api
33 changes: 33 additions & 0 deletions docs/installation.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
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
:external+finufft:doc:`finufft <install>` and
:external+finufft:doc:`cufinufft <install_gpu>`.


Pytorch-FINUFFT also requires ``pytorch`` 2.0 or greater. See the installation
matrix on `Pytorch's website <https://pytorch.org/get-started/>`_.


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.
35 changes: 35 additions & 0 deletions docs/make.bat
Original file line number Diff line number Diff line change
@@ -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
6 changes: 6 additions & 0 deletions docs/requirements.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
sphinx
nbsphinx
sphinx_copybutton
sphinx-gallery
pydata-sphinx-theme
texext

0 comments on commit cbd664c

Please sign in to comment.