Update for building document site (#12)

* update uv files

* update to add docstrings

* update for typehint

* add fles for docs

* update .gitignore

* update

* update for CI

* update

* update README.md

Author: shunk031

.github/workflows/gh-pages.yaml

@@ -0,0 +1,42 @@
+name: Document
+
+on: push
+
+# Allow one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Typo check
+        uses: crate-ci/typos@v1.29.0
+
+      - name: Setup python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Install dependencies
+        run: |
+          make setup
+          make install
+
+      - name: Build HTML
+        run: |
+          make html
+
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v4
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./public
+          publish_branch: gh-pages

.gitignore

@@ -1,7 +1,9 @@
 # Created by https://www.toptal.com/developers/gitignore/api/python
 # Edit at https://www.toptal.com/developers/gitignore?templates=python
 
+*.bk
 *.png
+*.gif
 *.json
 *.safetensors
 

Makefile

@@ -6,26 +6,34 @@
 setup:
 	pip install -U uv
 
-.PHONY: install
+.PHONY: install-training
 install:
 	uv sync --extra training
 
+.PHONY: install-doc
+install-doc:
+	uv sync --extra doc
+
 #
 # linter/formatter/typecheck
 #
 
 .PHONY: lint
-lint: install
+lint: install-training
 	uv run ruff check --output-format=github .
 
 .PHONY: format
-format: install
+format: install-training
 	uv run ruff format --check --diff .
 
 .PHONY: typecheck
 typecheck: install
 	uv run mypy --cache-dir=/dev/null .
 
 .PHONY: test
-test: install
+test: install-training
 	uv run pytest -vsx --log-cli-level=INFO
+
+.PHONY: html
+html: install-doc
+	uv run sphinx-build -M html docs/source docs/build

README.md

@@ -1,7 +1,8 @@
 # 🤗 Noise Conditional Score Networks
 
 [![CI](https://github.com/py-img-gen/diffusers-ncsn/actions/workflows/ci.yaml/badge.svg)](https://github.com/py-img-gen/diffusers-ncsn/actions/workflows/ci.yaml) 
-[![](https://img.shields.io/badge/Official_code-GitHub-green)](https://github.com/ermongroup/ncsn)
+[![Document](https://github.com/py-img-gen/diffusers-ncsn/actions/workflows/gh-pages.yaml/badge.svg)](https://github.com/py-img-gen/diffusers-ncsn/actions/workflows/gh-pages.yaml)
+[![ermongroup/ncsn](https://img.shields.io/badge/Official_code-GitHub-green)](https://github.com/ermongroup/ncsn)
 [![Model on HF](https://img.shields.io/badge/🤗%20Model%20on%20HF-py--img--gen/ncsn--mnist-D4AA00)](https://huggingface.co/py-img-gen/ncsn-mnist)
 
 [`🤗 diffusers`](https://github.com/huggingface/diffusers) implementation of the paper ["Generative Modeling by Estimating Gradients of the Data Distribution" [Yang+ NeurIPS'19]](https://arxiv.org/abs/1907.05600).

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)

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

docs/source/api/pipeline/index.md

@@ -0,0 +1,8 @@
+# Pipeline
+
+```{toctree}
+:maxdepth: 2
+:caption: Pipeline:
+
+pipeline-ncsn
+```

docs/source/api/pipeline/pipeline-ncsn.md

@@ -0,0 +1,16 @@
+# Pipeline for NCSN
+
+{py:class}`~ncsn.pipeline_ncsn.NCSNPipeline` is a pipeline for training and inference of Noise Conditional Score Networks (NCSN) proposed by by Yang Song and Stefano Ermon in the paper [Generative Modeling by Estimating Gradients of the Data Distribution](https://arxiv.org/abs/1907.05600). The pipeline is designed to be used with the 
+{py:class}`~ncsn.unet.UNet2DModelForNCSN` model and the {py:class}`~ncsn.scheduler.AnnealedLangevinDynamicsScheduler` scheduler.
+
+The abstract of the paper is the following:
+
+> We introduce a new generative model where samples are produced via Langevin dynamics using gradients of the data distribution estimated with score matching. Because gradients can be ill-defined and hard to estimate when the data resides on low-dimensional manifolds, we perturb the data with different levels of Gaussian noise, and jointly estimate the corresponding scores, i.e., the vector fields of gradients of the perturbed data distribution for all noise levels. For sampling, we propose an annealed Langevin dynamics where we use gradients corresponding to gradually decreasing noise levels as the sampling process gets closer to the data manifold. Our framework allows flexible model architectures, requires no sampling during training or the use of adversarial methods, and provides a learning objective that can be used for principled model comparisons. Our models produce samples comparable to GANs on MNIST, CelebA and CIFAR-10 datasets, achieving a new state-of-the-art inception score of 8.87 on CIFAR-10. Additionally, we demonstrate that our models learn effective representations via image inpainting experiments.
+
+## NCSNPipeline
+
+```{eval-rst}
+.. autoclass:: ncsn.pipeline_ncsn.NCSNPipeline
+   :members:
+   :special-members:
+```

docs/source/api/scheduler/index.md

@@ -0,0 +1,8 @@
+# Scheduler
+
+```{toctree}
+:maxdepth: 2
+:caption: Scheduler:
+
+scheduling-ncsn
+```

docs/source/api/scheduler/scheduling-ncsn.md

@@ -0,0 +1,21 @@
+# Annealed Langevin Dynamics Scheduler
+
+{py:class}`~ncsn.scheduler.AnnealedLangevinDynamicsScheduler` is a scheduler that uses Langevin dynamics to sample from the posterior distribution of the model parameters. The scheduler anneals the temperature of the Langevin dynamics over time, starting from a high temperature and gradually decreasing it to a low temperature. The scheduler is based on the paper [Generative Modeling by Estimating Gradients of the Data Distribution](https://arxiv.org/abs/1907.05600) by Yang Song and Stefano Ermon. Stanford AI Lab.
+
+The abstract of the paper is the following:
+> We introduce a new generative model where samples are produced via Langevin dynamics using gradients of the data distribution estimated with score matching. Because gradients can be ill-defined and hard to estimate when the data resides on low-dimensional manifolds, we perturb the data with different levels of Gaussian noise, and jointly estimate the corresponding scores, i.e., the vector fields of gradients of the perturbed data distribution for all noise levels. For sampling, we propose an annealed Langevin dynamics where we use gradients corresponding to gradually decreasing noise levels as the sampling process gets closer to the data manifold. Our framework allows flexible model architectures, requires no sampling during training or the use of adversarial methods, and provides a learning objective that can be used for principled model comparisons. Our models produce samples comparable to GANs on MNIST, CelebA and CIFAR-10 datasets, achieving a new state-of-the-art inception score of 8.87 on CIFAR-10. Additionally, we demonstrate that our models learn effective representations via image inpainting experiments.
+
+## AnnealedLangevinDynamicsScheduler
+
+```{eval-rst}
+.. autoclass:: ncsn.scheduler.AnnealedLangevinDynamicsScheduler
+   :members:
+   :special-members:
+```
+
+## AnnealedLangevinDynamicsOutput
+
+```{eval-rst}
+.. autoclass:: ncsn.scheduler.AnnealedLangevinDynamicsOutput
+   :members:
+```

docs/source/api/unet/index.md

@@ -0,0 +1,8 @@
+# UNet
+
+```{toctree}
+:maxdepth: 2
+:caption: UNet:
+
+unet-2d-ncsn
+```

docs/source/api/unet/unet-2d-ncsn.md

@@ -0,0 +1,15 @@
+# UNet2DModel for NCSN
+
+{py:class}`~ncsn.unet.UNet2DModelForNCSN` is a 2D U-Net model suitable for Noise Conditional Score Networks (NCSN) proposed by by Yang Song and Stefano Ermon in the paper [Generative Modeling by Estimating Gradients of the Data Distribution](https://arxiv.org/abs/1907.05600). The model inherits from the diffuser's {py:class}`~diffusers.UNet2DModel` and is designed to be used with the {py:class}`~ncsn.scheduler.AnnealedLangevinDynamicsScheduler` scheduler.
+
+The abstract of the paper is the following:
+
+> We introduce a new generative model where samples are produced via Langevin dynamics using gradients of the data distribution estimated with score matching. Because gradients can be ill-defined and hard to estimate when the data resides on low-dimensional manifolds, we perturb the data with different levels of Gaussian noise, and jointly estimate the corresponding scores, i.e., the vector fields of gradients of the perturbed data distribution for all noise levels. For sampling, we propose an annealed Langevin dynamics where we use gradients corresponding to gradually decreasing noise levels as the sampling process gets closer to the data manifold. Our framework allows flexible model architectures, requires no sampling during training or the use of adversarial methods, and provides a learning objective that can be used for principled model comparisons. Our models produce samples comparable to GANs on MNIST, CelebA and CIFAR-10 datasets, achieving a new state-of-the-art inception score of 8.87 on CIFAR-10. Additionally, we demonstrate that our models learn effective representations via image inpainting experiments.
+
+## UNet2DModelForNCSN
+
+```{eval-rst}
+.. autoclass:: ncsn.unet.UNet2DModelForNCSN
+   :members:
+   :special-members:
+```

docs/source/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
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+import os
+import sys
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+
+sys.path.insert(0, os.path.abspath("../../../src"))
+
+from datetime import datetime
+
+from sphinx_pyproject import SphinxConfig
+
+config = SphinxConfig(pyproject_file="../../pyproject.toml")
+
+
+project = config.name
+copyright = f"{datetime.today().year}, {config.author}"
+
+author = config.author
+release = config.version
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "myst_parser",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.viewcode",
+    "sphinx_autodoc_typehints",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = ["build"]
+
+source_suffix = [".rst", ".md"]
+
+# -- Extension configuration -------------------------------------------------
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "torch": ("https://pytorch.org/docs/stable", None),
+    "transformers": ("https://huggingface.co/docs/transformers/master/en", None),
+    "diffusers": ("https://huggingface.co/docs/diffusers/main/en", None),
+}
+
+# Tell myst-parser to assign header anchors for h1-h3.
+myst_heading_anchors = 3
+
+# By default, sort documented members by type within classes and modules.
+autodoc_member_order = "groupwise"
+
+python_use_unqualified_type_names = True
+
+# Include default values when documenting parameter types.
+typehints_defaults = "comma"
+
+# -- 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"]
+html_favicon = "https://huggingface.co/front/assets/huggingface_logo-noborder.svg"

docs/source/index.md

@@ -0,0 +1,12 @@
+```{include} ../../README.md
+```
+
+```{toctree}
+:maxdepth: 2
+:hidden:
+:caption: API Reference:
+
+api/unet/index
+api/scheduler/index
+api/pipeline/index
+```

pyproject.toml

@@ -2,6 +2,10 @@
 name = "diffusers-ncsn"
 version = "0.1.0"
 description = "Diffusers implementation of Noise Conditional Score Networks (NCSN) [Yang+ NeuriPS'19]"
+authors = [
+    { name = "Shunsuke Kitada", email = "shunsuke.kitada.0831@gmail.com" },
+    { name = "Image Generation with Python", email = "python.image.generation@gmail.com" },
+]
 readme = "README.md"
 requires-python = ">=3.10"
 dependencies = [
@@ -14,6 +18,13 @@ dependencies = [
 
 [project.optional-dependencies]
 training = ["matplotlib>=3.10.0"]
+doc = [
+    "sphinx-pyproject>=0.3.0",
+    "sphinx>=8.1.3",
+    "furo>=2024.8.6",
+    "myst-parser>=4.0.0",
+    "sphinx-autodoc-typehints>=3.0.0",
+]
 
 [dependency-groups]
 dev = ["mypy>=1.0.0", "pytest>=6.0.0", "ruff>=0.1.5"]

src/ncsn/__init__.py

@@ -0,0 +1,10 @@
+from importlib.metadata import version
+
+from ncsn.pipeline_ncsn import NCSNPipeline
+
+__version__ = version("diffusers-ncsn")
+
+
+__all__ = [
+    "NCSNPipeline",
+]