From d9ccf670cf279660923852338627f3e330a122fc Mon Sep 17 00:00:00 2001
From: Matthew Feickert <matthew.feickert@cern.ch>
Date: Tue, 10 Oct 2023 15:39:16 -0500
Subject: [PATCH] docs: Add docstring for public method

---
 docs/api.rst                       | 11 +++++
 src/pyhf/experimental/modifiers.py | 66 ++++++++++++++++++++++++++++++
 2 files changed, 77 insertions(+)

diff --git a/docs/api.rst b/docs/api.rst
index 56f65a211a..f35903af05 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -226,6 +226,17 @@ Utilities
    digest
    citation
 
+Experimental
+------------
+
+.. currentmodule:: pyhf.experimental
+
+.. autosummary::
+   :toctree: _generated/
+   :nosignatures:
+
+   modifiers
+
 Contrib
 -------
 
diff --git a/src/pyhf/experimental/modifiers.py b/src/pyhf/experimental/modifiers.py
index daf2471dca..620fcf2641 100644
--- a/src/pyhf/experimental/modifiers.py
+++ b/src/pyhf/experimental/modifiers.py
@@ -173,6 +173,72 @@ def apply(self, pars):
 def add_custom_modifier(
     func_name: str, deps: list[str], new_params: dict[str, dict[str, Sequence[float]]]
 ) -> dict[str, tuple[BaseBuilder, BaseApplier]]:
+    r"""
+    Add a custom modifier type with the modifier data defined through a custom
+    numexpr string expression.
+
+    Example:
+
+        >>> import pyhf
+        >>> import pyhf.experimental.modifiers
+        >>> pyhf.set_backend("numpy")
+        >>> new_params = {
+        ...     "m1": {"inits": (1.0,), "bounds": ((-5.0, 5.0),)},
+        ...     "m2": {"inits": (1.0,), "bounds": ((-5.0, 5.0),)},
+        ... }
+        >>> expanded_pyhf = pyhf.experimental.modifiers.add_custom_modifier(
+        ...     "custom", ["m1", "m2"], new_params
+        ... )
+        >>> model = pyhf.Model(
+        ...     {
+        ...         "channels": [
+        ...             {
+        ...                 "name": "singlechannel",
+        ...                 "samples": [
+        ...                     {
+        ...                         "name": "signal",
+        ...                         "data": [10, 20],
+        ...                         "modifiers": [
+        ...                             {
+        ...                                 "name": "f2",
+        ...                                 "type": "custom",
+        ...                                 "data": {"expr": "m1"},
+        ...                             },
+        ...                         ],
+        ...                     },
+        ...                     {
+        ...                         "name": "background",
+        ...                         "data": [100, 150],
+        ...                         "modifiers": [
+        ...                             {
+        ...                                 "name": "f1",
+        ...                                 "type": "custom",
+        ...                                 "data": {"expr": "m1+(m2**2)"},
+        ...                             },
+        ...                         ],
+        ...                     },
+        ...                 ],
+        ...             }
+        ...         ]
+        ...     },
+        ...     modifier_set=expanded_pyhf,
+        ...     poi_name="m1",
+        ...     validate=False,
+        ...     batch_size=1,
+        ... )
+        >>> model.config.modifiers
+        [('f1', 'custom'), ('f2', 'custom')]
+
+    Args:
+        func_name (:obj:`str`): The name of the custom modifier type.
+        deps (:obj:`list`): The names of the new parameters of the modifier
+         function.
+        new_params (:obj:`dict`): The new parameters.
+
+    Returns:
+        :obj:`dict`: The updated ``pyhf.modifiers.histfactory_set`` with the added
+        custom modifier type.
+    """
     _builder = make_builder(func_name, deps, new_params)
     _applier = make_applier(func_name, deps, new_params)