docs

.github/workflows/docs.yml

@@ -0,0 +1,44 @@
+name: docs
+
+on:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - main
+
+jobs:
+  test-ubuntu:
+    name: "docs on ${{ matrix.python-version }} on ${{ matrix.os }}"
+    runs-on: "${{ matrix.os }}"
+    strategy:
+      matrix:
+        python-version: ["3.10"]
+        os: [ubuntu-latest]
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v1
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          sudo apt-get update
+          sudo apt install graphviz graphviz-dev
+          sudo apt install -y pandoc
+          python -m pip install --upgrade pip
+          pip install .
+          pip install -r docs/requirements.txt
+
+      - name: Setup Graphviz
+        uses: ts-graphviz/setup-graphviz@v1
+
+      - name: Test doctests
+        run: |
+          cd docs
+          make doctest
+      - name: Test docs to HTML
+        run: |
+          cd docs
+          make html

.gitignore

@@ -12,3 +12,4 @@ experimental
 notes
 build
 playground.ipynb
+docs/_build

README.md

@@ -1,5 +1,5 @@
 <h5 align="center">
-<img width="200px" src="assets/finitediffx_logo.svg"> <br>
+<img width="200px" src="assets/logo.svg"> <br>
 
 <br>
 
@@ -20,22 +20,6 @@
 </h5>
 
 Differentiable finite difference tools in `jax`
-Implements :
-
-**`Array` accepting functions:**
-
-- `difference(array, axis, accuracy, step_size, method, derivative)`
-- `gradient(array, accuracy, method, step_size)`
-- `jacobian(array, accuracy, method, step_size)`
-- `divergence(array, accuracy, step_size, method, keepdims)`
-- `hessian(array, accuracy, method, step_size)`
-- `laplacian(array, accuracy, method, step_size)`
-- `curl(array, step_size, method, keep_dims)`
-
-**Function transformation:**
-
-- `fgrad`, and `value_and_fgrad` : similar to `jax.grad` and `jax.value_and_grad` but with finite difference approximation.
-- `define_fdjvp`: define `custom_jvp` rules using finite difference approximation (see example below).
 
 ## 🛠️ Installation<a id="installation"></a>
 

docs/API/api.rst

@@ -0,0 +1,12 @@
+Public API
+=================================================
+
+.. currentmodule:: finitediffx
+
+.. toctree::
+   :maxdepth: 2
+   :caption: API Documentation
+
+   array
+   transformation
+

docs/API/array.rst

@@ -0,0 +1,11 @@
+Array finite difference
+---------------------------------
+.. currentmodule:: finitediffx
+
+.. autofunction:: curl
+.. autofunction:: difference
+.. autofunction:: divergence
+.. autofunction:: gradient
+.. autofunction:: hessian
+.. autofunction:: jacobian
+.. autofunction:: laplacian

docs/API/transformation.rst

@@ -0,0 +1,8 @@
+Function transformation
+---------------------------------
+.. currentmodule:: finitediffx
+
+.. autofunction:: define_fdjvp
+.. autofunction:: fgrad
+.. autofunction:: value_and_fgrad
+.. autoclass:: Offset

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)

docs/conf.py

@@ -0,0 +1,142 @@
+# source https://raw.githubusercontent.com/deepmind/dm-haiku/main/docs/conf.py
+
+
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- 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.
+#
+
+from __future__ import annotations
+
+import doctest
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath(".."))
+
+import sphinxcontrib.katex as katex
+
+# -- Project information -----------------------------------------------------
+
+project = "finitediffx"
+copyright = "2023, Mahmoud Asem"
+author = "Mahmoud Asem"
+
+
+# -- General configuration ---------------------------------------------------
+master_doc = "index"
+
+html_static_path = ["_static"]
+html_logo = "_static/logo.svg"
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "sphinx_copybutton",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.doctest",
+    "sphinx.ext.inheritance_diagram",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
+    "sphinxcontrib.katex",
+    "sphinx.ext.graphviz",
+    "sphinx_autodoc_typehints",
+    "nbsphinx",
+    "IPython.sphinxext.ipython_console_highlighting",
+]
+
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+
+# -- Options for autodoc -----------------------------------------------------
+
+autodoc_default_options = {
+    "member-order": "bysource",
+    "special-members": True,
+    "exclude-members": "__repr__, __str__, __weakref__",
+}
+
+
+# -- Options for HTML output -------------------------------------------------
+
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "sphinx_book_theme"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+# html_static_path = ["_static"]
+
+
+html_theme_options = {
+    "show_toc_level": 2,
+    "repository_url": "https://github.com/ASEM000/finitediffx",
+    "use_repository_button": True,
+    "collapse_navigation": False,
+    "navigation_depth": 4,
+    "globaltoc_collapse": True,
+    "globaltoc_maxdepth": None,
+}
+
+
+# -- Options for doctest -----------------------------------------------------
+
+doctest_test_doctest_blocks = "true"
+doctest_global_setup = """
+import jax
+import jax.numpy as jnp
+import finitediffx as sk
+"""
+doctest_default_flags = (
+    doctest.ELLIPSIS
+    | doctest.IGNORE_EXCEPTION_DETAIL
+    | doctest.DONT_ACCEPT_TRUE_FOR_1
+    | doctest.NORMALIZE_WHITESPACE
+)
+
+
+# -- Options for katex ------------------------------------------------------
+
+# See: https://sphinxcontrib-katex.readthedocs.io/en/0.4.1/macros.html
+latex_macros = r"""
+    \def \d              #1{\operatorname{#1}}
+"""
+
+# Translate LaTeX macros to KaTeX and add to options for HTML builder
+katex_macros = katex.latex_defs_to_katex_macros(latex_macros)
+katex_options = "macros: {" + katex_macros + "}"
+
+# Add LaTeX macros for LATEX builder
+latex_elements = {"preamble": latex_macros}
+
+# -- nbsphinx configuration --------------------------------------------------
+
+nbsphinx_execute = "never"
+nbsphinx_codecell_lexer = "ipython"
+nbsphinx_kernel_name = "python"
+nbsphinx_timeout = 180
+
+# Tell sphinx-autodoc-typehints to generate stub parameter annotations including
+# types, even if the parameters aren't explicitly documented.
+always_document_param_types = True

docs/examples.rst

@@ -0,0 +1,8 @@
+Examples
+======================
+
+.. toctree::
+    :caption: Examples
+    :maxdepth: 1
+
+    notebooks/getting_started

docs/index.rst

@@ -0,0 +1,64 @@
+🛠️ Installation
+----------------
+
+Install from github::
+
+   pip install finitediffx
+
+
+🏃 Quick example
+------------------
+
+.. code-block:: python
+
+    import jax.numpy as jnp
+    import finitediffx as fdx
+
+    # lets first define a vector valued function F: R^3 -> R^3
+    # F = F1, F2
+    # F1 = x^2 + y^3
+    # F2 = x^4 + y^3
+    # F3 = 0
+    # F = [x**2 + y**3, x**4 + y**3, 0]
+
+    x, y, z = [jnp.linspace(0, 1, 100)] * 3
+    dx, dy, dz = x[1] - x[0], y[1] - y[0], z[1] - z[0]
+    X, Y, Z = jnp.meshgrid(x, y, z, indexing="ij")
+    F1 = X**2 + Y**3
+    F2 = X**4 + Y**3
+    F3 = jnp.zeros_like(F1)
+    F = jnp.stack([F1, F2, F3], axis=0)
+
+    # ∇.F : the divergence of F
+    divF = fdx.divergence(
+        F,
+        step_size=(dx, dy, dz),
+        keepdims=False,
+        accuracy=6,
+        method="central",
+    )
+
+
+
+.. toctree::
+    :caption: Examples
+    :maxdepth: 1
+
+    examples
+
+
+.. toctree::
+    :caption: API Documentation
+    :maxdepth: 1
+
+
+    API/api
+
+Apache2.0 License.
+
+Indices
+=======
+
+* :ref:`genindex`
+
+