From f59ab43b596b067ebb1dac27aae04598d00d3955 Mon Sep 17 00:00:00 2001
From: Remco de Boer <29308176+redeboer@users.noreply.github.com>
Date: Mon, 20 May 2024 23:06:42 +0200
Subject: [PATCH] DOC: improve docstrings multichannel Breit-Wigner

---
 docs/_extend_docstrings.py       | 36 ++++++++++++++++++++++++++++++--
 src/ampform/dynamics/__init__.py |  4 ++++
 2 files changed, 38 insertions(+), 2 deletions(-)

diff --git a/docs/_extend_docstrings.py b/docs/_extend_docstrings.py
index 0db2d3c87..ef0b1e84a 100644
--- a/docs/_extend_docstrings.py
+++ b/docs/_extend_docstrings.py
@@ -373,6 +373,36 @@ def extend_is_within_phasespace() -> None:
     )
 
 
+def extend_MultichannelBreitWigner() -> None:
+    from ampform.dynamics import (
+        ChannelArguments,
+        MultichannelBreitWigner,
+        SimpleBreitWigner,
+    )
+
+    s, m0, w0 = sp.symbols("s m0 Gamma0", nonnegative=True)
+    channels = [
+        ChannelArguments(*sp.symbols("Gamma1 m_a1 m_b1 L1 d", nonnegative=True)),
+        ChannelArguments(*sp.symbols("Gamma2 m_a2 m_b2 L2 d", nonnegative=True)),
+    ]
+    expr = MultichannelBreitWigner(s, m0, channels=channels)
+    _append_latex_doit_definition(expr)
+    bw = SimpleBreitWigner(s, m0, w0)
+    _append_to_docstring(
+        MultichannelBreitWigner,
+        Rf"""
+    with :math:`{sp.latex(bw)}` defined by Equation :eq:`SimpleBreitWigner`, a
+    `SimpleBreitWigner`.
+    """,
+    )
+    _append_to_docstring(
+        ChannelArguments.formulate_width,
+        Rf"""
+    .. math:: {sp.latex(channels[0].formulate_width(s, m0))}
+    """,
+    )
+
+
 def extend_PhaseSpaceFactor() -> None:
     from ampform.dynamics.phasespace import PhaseSpaceFactor
 
@@ -743,8 +773,10 @@ def _create_latex_doit_definition(expr: sp.Expr, deep: bool = False) -> str:
 
 
 def _append_to_docstring(class_type: Callable | type, appended_text: str) -> None:
-    assert class_type.__doc__ is not None
-    class_type.__doc__ += appended_text
+    if class_type.__doc__ is None:
+        class_type.__doc__ = appended_text
+    else:
+        class_type.__doc__ += appended_text
 
 
 def __generate_transitions_cached(
diff --git a/src/ampform/dynamics/__init__.py b/src/ampform/dynamics/__init__.py
index f899c4163..4b9f33aac 100644
--- a/src/ampform/dynamics/__init__.py
+++ b/src/ampform/dynamics/__init__.py
@@ -135,6 +135,8 @@ def _latex_repr_(self, printer: LatexPrinter, *args) -> str:
 
 @unevaluated
 class MultichannelBreitWigner(sp.Expr):
+    """`BreitWigner` for multiple channels."""
+
     s: Any
     mass: Any
     channels: list[ChannelArguments] = argument(sympify=False)
@@ -155,6 +157,8 @@ def _latex_repr_(self, printer: LatexPrinter, *args) -> str:
 
 @frozen
 class ChannelArguments:
+    """Arguments for a channel in a `MultichannelBreitWigner`."""
+
     width: Any
     m1: Any = 0
     m2: Any = 0