Add documentation

master · master · commit 76e7d7643474 · 2025-04-22T23:05:45.000+02:00
diff --git a/.gitignore b/.gitignore
@@ -4,3 +4,4 @@ __pycache__
 build
 dist
 *.egg-info
+docs/_build/
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -0,0 +1,22 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version, and other tools you might need
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+   configuration: docs/conf.py
+
+# Optionally, but recommended,
+# declare the Python requirements required to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+  install:
+    - requirements: requirements_dev.txt
diff --git a/README.md b/README.md
@@ -3,6 +3,7 @@
 [![PyPI](https://img.shields.io/pypi/v/tensorflow-riemopt.svg)](https://pypi.org/project/tensorflow-riemopt/)
 [![arXiv](https://img.shields.io/badge/arXiv-2105.13921-b31b1b.svg)](https://arxiv.org/abs/2105.13921)
 [![Build Status](https://github.com/master/tensorflow-riemopt/actions/workflows/build.yml/badge.svg)](https://github.com/master/tensorflow-riemopt/actions)
+[![Documentation Status](https://readthedocs.org/projects/tensorflow-riemopt/badge/?version=latest)](https://tensorflow-riemopt.readthedocs.io)
 [![Coverage Status](https://coveralls.io/repos/github/master/tensorflow-riemopt/badge.svg)](https://coveralls.io/github/master/tensorflow-riemopt)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/python/black)
 [![License](https://img.shields.io/:license-mit-blue.svg)](https://badges.mit-license.org)
diff --git a/docs/Makefile b/docs/Makefile
@@ -0,0 +1,19 @@
+## Makefile for building the Sphinx documentation
+# You can also run sphinx-build directly: sphinx-build -b html . _build/html
+
+# Directory for source files
+SOURCEDIR = .
+# Directory for build output
+BUILDDIR  = _build
+
+.PHONY: help clean html
+
+help:
+	@echo "Please use 'make <target>' where <target> is one of"
+	@echo "  html      to build the HTML documentation"
+
+html:
+	@sphinx-build -b html $(SOURCEDIR) $(BUILDDIR)/html
+
+clean:
+	@rm -rf $(BUILDDIR)
diff --git a/docs/api/index.rst b/docs/api/index.rst
@@ -0,0 +1,13 @@
+API Reference
+=============
+
+This section contains the API reference for the `tensorflow_riemopt` package.
+
+.. toctree::
+   :maxdepth: 2
+   :titlesonly:
+
+   variable
+   layers
+   manifolds
+   optimizers
diff --git a/docs/api/layers.rst b/docs/api/layers.rst
@@ -0,0 +1,9 @@
+Layers Package
+==============
+
+This package provides manifold-aware neural network layers.
+
+.. automodule:: tensorflow_riemopt.layers
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/api/manifolds.rst b/docs/api/manifolds.rst
@@ -0,0 +1,13 @@
+Manifolds Package
+=================
+
+The module implements a variety of Riemannian manifolds as Python classes. Each manifold class encapsulates core geometric operations, such as distance functions, geodesics, exponential/logarithm maps, projections, and retractions, enabling integration of non-Euclidean geometry into neural network models.
+
+Certain manifolds (e.g., SPD and Stiefel) can be endowed with different Riemannian metrics, resulting in distinct operations implemented in their corresponding classes.
+
+.. automodule:: tensorflow_riemopt.manifolds
+
+.. automodule:: tensorflow_riemopt.manifolds
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/api/optimizers.rst b/docs/api/optimizers.rst
@@ -0,0 +1,9 @@
+Optimizers Package
+==================
+
+The module provides Riemannian optimization algorithms for TensorFlow and its Keras API. These optimizers adapt standard methods to manifold settings by projecting gradients onto tangent spaces, retracting updates back onto the manifold, and optionally using vector transport to handle adaptive schemes.
+
+.. automodule:: tensorflow_riemopt.optimizers
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/api/variable.rst b/docs/api/variable.rst
@@ -0,0 +1,9 @@
+Variable Utilities
+==================
+
+Utilities for associating TensorFlow variables with Riemannian manifolds.
+
+.. automodule:: tensorflow_riemopt.variable
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/conf.py b/docs/conf.py
@@ -0,0 +1,59 @@
+# Configuration file for the Sphinx documentation builder.
+import os
+import sys
+
+# Add project root to sys.path for autodoc
+sys.path.insert(0, os.path.abspath('..'))
+
+project = 'tensorflow-riemopt'
+author = 'Oleg Smirnov'
+# The full version, including alpha/beta/rc tags
+release = '0.3.0'
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.mathjax',
+    'sphinx_autodoc_typehints',
+    'myst_parser',
+]
+
+templates_path = ['_templates']
+# Exclude Jupyter checkpoints
+exclude_patterns = ['**.ipynb_checkpoints']
+
+# HTML output
+html_title = "tensorflow-riemopt documentation"
+html_theme = 'pydata_sphinx_theme'
+html_static_path = ['_static']
+html_theme_options = {
+    "primary_sidebar_end": [],
+    "icon_links": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/master/tensorflow-riemopt",
+            "icon": "fa-brands fa-square-github",
+            "type": "fontawesome",
+        }
+    ],
+    "use_edit_page_button": False,
+    "collapse_navigation": True,
+}
+html_context = {
+    "github_user": "master",
+    "github_repo": "tensorflow-riemopt",
+    "doc_path": "docs",
+    "default_mode": "light",
+}
+
+# Autodoc settings
+autodoc_member_order = 'bysource'
+autoclass_content = 'both'
+
+# Source suffix and master doc
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.md': 'markdown',
+}
+master_doc = 'index'
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,62 @@
+# TensorFlow RiemOpt
+
+**TensorFlow RiemOpt** is a flexible, extensible library for Riemannian optimization and geometric deep learning in TensorFlow. It provides:
+- Riemannian manifold classes with associated exponential and logarithmic maps, geodesics, and transports
+- Riemannian optimizers (SGD, RMSProp, and adaptive methods such as Adam)
+- Manifold-aware TensorFlow/Keras layers (e.g., Embedding)
+
+## Installation
+
+Install via PyPI:
+
+```bash
+pip install tensorflow-riemopt
+```
+
+## Quickstart
+
+```{figure} _static/usage.png
+:align: right
+:width: 300px
+
+Example: SPDNet classification on SPD manifold
+```
+
+```python
+import tensorflow as tf
+from tensorflow_riemopt.optimizers import ConstrainedRMSprop
+from tensorflow_riemopt.manifolds import Grassmannian
+from tensorflow_riemopt.variable import assign_to_manifold
+
+# Create a variable on the Grassmannian manifold (3×2 matrix)
+manifold = Grassmannian()
+x = tf.Variable(tf.random.uniform((3, 2)), dtype=tf.float32)
+assign_to_manifold(x, manifold)
+
+# Define a simple loss (squared Frobenius norm)
+with tf.GradientTape() as tape:
+    loss = tf.reduce_sum(x * x)
+
+# Compute gradients and update
+grads = tape.gradient(loss, [x])
+opt = ConstrainedRMSprop(learning_rate=0.1, rho=0.9)
+opt.apply_gradients(zip(grads, [x]))
+```
+
+## Documentation
+
+```{toctree}
+:titlesonly:
+:glob:
+:maxdepth: 1
+
+api/*
+```
+
+## Examples
+
+The repository provides several fully implemented example network projects:
+
+- **GrNet**: Deep networks on Grassmann manifolds. [examples/grnet](https://github.com/master/tensorflow-riemopt/tree/master/examples/grnet)
+- **LieNet**: Deep learning on Lie groups for action recognition. [examples/lienet](https://github.com/master/tensorflow-riemopt/tree/master/examples/lienet)
+- **SPDNet**: Riemannian network for SPD matrix learning. [examples/spdnet](https://github.com/master/tensorflow-riemopt/tree/master/examples/spdnet)
diff --git a/requirements_dev.txt b/requirements_dev.txt
@@ -2,3 +2,7 @@ pip>=20.0.0
 black
 coveralls
 pytest-cov
+sphinx
+myst-parser
+sphinx-autodoc-typehints
+pydata-sphinx-theme
diff --git a/setup.py b/setup.py
@@ -3,7 +3,7 @@
 
 setup(
     name="tensorflow-riemopt",
-    version="0.2.0",
+    version="0.3.0",
     description="a library for optimization on Riemannian manifolds",
     long_description=open("README.md").read(),
     long_description_content_type="text/markdown",
