Cost gradient support (#936)

Add gradient support for all builtin cost functions except the Template
cost function (whose gradients may be added later).

Gradient support means the following. You can now pass a user-defined
model gradient to each supported cost function. Minuit will
automatically detect whether the gradient is available and make use of
it. This behavior is now properly documented and can be overridden by
passing a boolean to the keyword `grad` of the Minuit constructor.

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

doc/conf.py

@@ -54,6 +54,7 @@
 autoclass_content = "both"
 autosummary_generate = True
 autodoc_member_order = "groupwise"
+autodoc_type_aliases = {"ArrayLike": "ArrayLike"}
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.

doc/plots/interactive.py

@@ -3,7 +3,7 @@
 from matplotlib import pyplot as plt
 
 
-# custom visualization, x and y are taken from outer scope
+# custom visualization; x, y, model are taken from outer scope
 def viz(args):
     plt.plot(x, y, "ok")
     xm = np.linspace(x[0], x[-1], 100)
@@ -18,4 +18,5 @@ def model(x, a, b):
 y = np.array([1.03, 1.58, 2.03, 2.37, 3.09])
 c = cost.LeastSquares(x, y, 0.1, model)
 m = Minuit(c, 0.5, 0.5)
-m.interactive(viz)  # calling m.interactive() uses LeastSquares.visualize
+m.interactive(viz)
+# m.interactive() also works and calls LeastSquares.visualize

pyproject.toml

@@ -95,10 +95,13 @@ filterwarnings = [
 
 [tool.ruff]
 select = [
-    "E", "F", # flake8
-    "D",      # pydocstyle
+    "E",
+    "F", # flake8
+    "D", # pydocstyle
+]
+extend-ignore = [
+    "D212", # multi-line-summary-first-line
 ]
-extend-ignore = ["D203", "D212"]
 src = ["src"]
 unfixable = [
     "F841", # Removes unused variables
@@ -112,8 +115,6 @@ convention = "numpy"
 ".ci/*.py" = ["D"]
 "bench/*.py" = ["D"]
 "doc/*.py" = ["D"]
-"setup.py" = ["D"]
-"cmake_ext.py" = ["D"]
 
 [tool.mypy]
 ignore_missing_imports = true

src/iminuit/_optional_dependencies.py

@@ -1,13 +1,17 @@
 import contextlib
 import warnings
 from iminuit.warnings import OptionalDependencyWarning
+from typing import Dict, Optional
 
 
 @contextlib.contextmanager
-def optional_module_for(functionality, *, replace=None, stacklevel=3):
+def optional_module_for(
+    functionality: str, *, replace: Optional[Dict[str, str]] = None, stacklevel: int = 3
+):
     try:
         yield
     except ModuleNotFoundError as e:
+        assert e.name is not None
         package = e.name.split(".")[0]
         if replace:
             package = replace.get(package, package)