DOC: hide sympified attributes from expression classes

Author: redeboer

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(

docs/conf.py

@@ -1,7 +1,10 @@
 from __future__ import annotations
 
+import importlib
+import inspect
 import os
 import sys
+from dataclasses import is_dataclass
 
 from sphinx_api_relink.helpers import (
     get_branch_name,
@@ -12,9 +15,51 @@
     set_intersphinx_version_remapping,
 )
 
+from ampform.sympy._decorator import get_sympy_fields  # noqa: PLC2701
+
 sys.path.insert(0, os.path.abspath("."))
 from _extend_docstrings import extend_docstrings  # noqa: PLC2701
 
+
+def _get_excluded_members() -> list[str]:
+    default_exclusions = {
+        "as_explicit",
+        "default_assumptions",
+        "doit",
+        "evaluate",
+        "is_commutative",
+        "is_extended_real",
+        "items",
+        "keys",
+        "precedence",
+        "values",
+    }
+    for cls in [
+        *_get_dataclasses_recursive("ampform"),
+    ]:
+        fields = get_sympy_fields(cls)
+        arg_names = {f.name for f in fields}
+        default_exclusions.update(arg_names)
+    return sorted(default_exclusions)
+
+
+def _get_dataclasses_recursive(module_name: str) -> list[type]:
+    module = importlib.import_module(module_name)
+    dataclass_list = _get_dataclasses(module)
+    for _, submodule in inspect.getmembers(module, inspect.ismodule):
+        if submodule.__name__.startswith(module_name):
+            dataclass_list.extend(_get_dataclasses_recursive(submodule.__name__))
+    return dataclass_list
+
+
+def _get_dataclasses(module):
+    dataclass_list = []
+    for _, obj in inspect.getmembers(module):
+        if inspect.isclass(obj) and is_dataclass(obj):
+            dataclass_list.append(obj)
+    return dataclass_list
+
+
 extend_docstrings()
 set_intersphinx_version_remapping({
     "ipython": {
@@ -85,18 +130,7 @@
 }
 author = "Common Partial Wave Analysis"
 autodoc_default_options = {
-    "exclude-members": ", ".join([
-        "as_explicit",
-        "default_assumptions",
-        "doit",
-        "evaluate",
-        "is_commutative",
-        "is_extended_real",
-        "items",
-        "keys",
-        "precedence",
-        "values",
-    ]),
+    "exclude-members": ", ".join(_get_excluded_members()),
     "members": True,
     "undoc-members": True,
     "show-inheritance": True,

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