Update RTD page (#48)

* Add landing page stub
* Add example notebook after some cleanup

To be prettified later...

README.md

@@ -4,11 +4,11 @@
 [![PyPI](https://badge.fury.io/py/fiddy.svg)](https://badge.fury.io/py/fiddy)
 [![Documentation](https://readthedocs.org/projects/fiddy/badge/?version=latest)](https://fiddy.readthedocs.io)
 
-Finite difference methods, for applications including gradient computation and gradient checks.
-
-Install with `pip install -e .`.
+[Finite difference methods](https://en.wikipedia.org/wiki/Finite_difference),
+for applications including gradient computation and gradient checks.
 
 # Important notes
+
 The output of your function of interest should be a NumPy array. If your function is scalar-valued, change it to a NumPy array with:
 ```python
 import numpy as np
@@ -19,6 +19,7 @@ def function(input_value: float) -> np.ndarray:
 ```
 
 # Installation
+
 Currently under development, please install from source.
 ```bash
 pip install -e .

doc/about.rst

@@ -0,0 +1,6 @@
+About fiddy
+===========
+
+Fiddy is a Python library implementing
+`finite difference methods <https://en.wikipedia.org/wiki/Finite_difference>`_,
+for applications including gradient computation and gradient checks.

doc/conf.py

@@ -36,13 +36,18 @@
     "sphinx.ext.napoleon",
     #    "sphinx_autodoc_typehints",  # FIXME fails
     "sphinx.ext.intersphinx",
+    "sphinx.ext.mathjax",
+    "nbsphinx",
+    "IPython.sphinxext.ipython_console_highlighting",
+    "recommonmark",
 ]
 
 intersphinx_mapping = {
     "petab": ("https://petab.readthedocs.io/en/stable/", None),
     "pandas": ("https://pandas.pydata.org/docs/", None),
     "numpy": ("https://numpy.org/devdocs/", None),
     "python": ("https://docs.python.org/3", None),
+    "amici": ("https://amici.readthedocs.io/en/latest/", None),
 }
 
 # sphinx-autodoc-typehints

examples/derivative.ipynb → doc/examples/derivative.ipynb

@@ -5,11 +5,13 @@
    "id": "1766a5fc",
    "metadata": {},
    "source": [
-    "We will approximate the derivative of the Rosenbrock function at `(1,0,0)`, with the forward and backward difference methods, and with two different step sizes.\n",
+    "# Example: Gradient approximation\n",
+    "\n",
+    "We will approximate the derivative of the Rosenbrock function at `(1,0,0)`, with the [forward and backward difference methods](https://en.wikipedia.org/wiki/Finite_difference#Basic_types), and with two different step sizes.\n",
     "\n",
     "We will also compute an approximation of the central difference, as the average of the forward and backward results.\n",
     "\n",
-    "Success will be determined by whether results between the different methods (forward, backward, central) are consistent (i.e. equal, within some tolerance).\n",
+    "Success will be determined by whether results between the different methods (forward, backward, central) are consistent (i.e., equal, within some tolerance).\n",
     "\n",
     "Function inputs and outputs are NumPy arrays of arbitrary positive dimension."
    ]
@@ -36,18 +38,21 @@
     "from fiddy.analysis import ApproximateCentral\n",
     "from fiddy.success import Consistency\n",
     "\n",
+    "# Point at which to compute the derivative\n",
     "point = np.array([1, 0, 0])\n",
+    "# Step sizes for finite differences\n",
     "sizes = [1e-10, 1e-5]\n",
+    "\n",
     "derivative = get_derivative(\n",
     "    function=rosen,\n",
     "    point=point,\n",
-    "    sizes=[1e-10, 1e-5],\n",
+    "    sizes=sizes,\n",
     "    method_ids=[MethodId.FORWARD, MethodId.BACKWARD],\n",
     "    direction_ids=[\"x\", \"y\", \"z\"],\n",
     "    analysis_classes=[ApproximateCentral],\n",
     "    success_checker=Consistency(rtol=1e-2, atol=1e-15),\n",
     ")\n",
-    "print(derivative.value)"
+    "print(\"Computed derivative:\", derivative.value)"
    ]
   },
   {
@@ -57,7 +62,7 @@
    "source": [
     "The full (`derivative.df_full`) or the concise (`derivative.df`) dataframe can be used for debugging gradients.\n",
     "\n",
-    "The IDs correspond to the directions in which finite differences were computed. These directions can be any vector in the function's parameter space. In this case directions were not specified, so the default directions were used, which is the standard basis."
+    "The IDs correspond to the directions in which finite differences were computed. These directions can be any vector in the function's parameter space. In this case, directions were not specified, so the default directions were used, which is the standard basis."
    ]
   },
   {
@@ -172,7 +177,7 @@
    "id": "14799145",
    "metadata": {},
    "source": [
-    "The `*_results` columns can be printed separatel to view the specific derivative values that were computed.\n",
+    "The `*_results` columns can be printed separately to view the specific derivative values that were computed.\n",
     "\n",
     "These values differ from the values reported in `derivative.values`. This is because the `success_checker` (`Consistency`) provides the derivative values as the average of all consistent derivative values. Consistency is checked on the level of `size`, so if any of the values for `1e-05` were inconsistent to the rest, they would not contribute to the average reported by the `Consistency` success checker."
    ]
@@ -343,7 +348,7 @@
    ],
    "source": [
     "expected_derivative = rosen_der(point)\n",
-    "print(expected_derivative)"
+    "print(f\"{expected_derivative=}\")"
    ]
   },
   {

doc/index.rst

@@ -5,6 +5,8 @@ Welcome to fiddy's documentation!
    :maxdepth: 2
    :caption: Contents:
 
+   about
+   examples/derivative
    modules
 
 Indices and tables

fiddy/derivative.py

@@ -132,7 +132,7 @@ def get_derivative(
     # TODO change to class that can be initialized with.. directional_derivative object?
     success_checker: Success,
     *args,
-    analysis_classes: list[Analysis] = None,
+    analysis_classes: list[type[Analysis]] = None,
     relative_sizes: bool = False,
     directions: list[Type.DIRECTION] | dict[str, Type.DIRECTION] = None,
     direction_ids: list[str] = None,

setup.cfg

@@ -4,11 +4,15 @@ all =
     %(examples)s
     %(tests)s
 doc =
-    sphinx<8
     docutils<0.19
+    ipython
+    mock
+    nbconvert
+    nbsphinx
+    recommonmark>=0.7.1
+    sphinx<8
     sphinx_rtd_theme
     sphinx-autodoc-typehints
-    mock
     %(amici)s
 amici =
     amici