fix docs

Author: unalmis

desc/integrals/bounce_integral.py

@@ -175,9 +175,9 @@ class Bounce2D(_Bounce):
 
     References
     ----------
-    .. [1] K. Unalmis et al., "Spectrally accurate, reverse-mode
-           differentiable bounce-averaging algorithm and its applications,"
-           Journal of Plasma Physics.
+    [1] K. Unalmis et al., "Spectrally accurate, reverse-mode
+        differentiable bounce-averaging algorithm and its applications,"
+        Journal of Plasma Physics.
 
     Examples
     --------

desc/objectives/_coils.py

@@ -2680,15 +2680,15 @@ class SurfaceCurrentRegularization(_Objective):
 
     """
 
-    weight_str = (
-        "weight : {float, ndarray}, optional"
-        "\n\tWeighting to apply to the Objective, relative to other Objectives."
-        "\n\tMust be broadcastable to to ``Objective.dim_f``"
-        "\n\tWhen used with QuadraticFlux objective, this acts as the regularization"
-        "\n\tparameter (with w^2 = lambda), with 0 corresponding to no regularization."
-        "\n\tThe larger this parameter is, the less complex the surface current will "
-        "be,\n\tbut the worse the normal field."
-    )
+    weight_str = """
+        weight : {float, ndarray}, optional
+            Weighting to apply to the Objective, relative to other Objectives.
+            Must be broadcastable to to ``Objective.dim_f``.
+            When used with QuadraticFlux objective, this acts as the regularization
+            parameter (with w^2 = lambda), with 0 corresponding to no regularization.
+            The larger this parameter is, the less complex the surface current will
+            be, but the worse the normal field.
+        """
     __doc__ = __doc__.rstrip() + collect_docs(
         target_default="``target=0``.",
         bounds_default="``target=0``.",

desc/objectives/_fast_ion.py

@@ -5,7 +5,7 @@
 from desc.integrals._interp_utils import check_nufft
 from desc.integrals.bounce_integral import Options
 
-from .objective_funs import _Objective, collect_docs, doc_bounce
+from .objective_funs import _clean_doc, _Objective, collect_docs, doc_bounce
 from .utils import errorif
 
 
@@ -44,7 +44,8 @@ class GammaC(_Objective):
     __doc__ = (
         __doc__.rstrip()
         + doc_bounce
-        + """
+        + "\n"
+        + _clean_doc("""
     Nemov : bool
         Whether to use the Γ_c as defined by Nemov et al. or Velasco et al.
         Default is Nemov. Set to ``False`` to use Velasco's.
@@ -56,7 +57,7 @@ class GammaC(_Objective):
         integrals. At finite resolution, an optimization using Velasco's metric
         may need to be evaluated by measuring decrease in Γ_c at a fixed number
         of toroidal transits.
-        """.rstrip()
+        """)
         + collect_docs(
             target_default="``target=0``.",
             bounds_default="``target=0``.",
@@ -203,19 +204,21 @@ class GammaLoss(_Objective):
 
     __doc__ = (
         __doc__.rstrip()
-        + doc_bounce.split("    Parameters\n    ----------\n", maxsplit=1)[0]
-        + """
+        + doc_bounce.split("Parameters\n----------\n", maxsplit=1)[0]
+        + _clean_doc("""
     Parameters
     ----------
     kind : {"delta", "alpha"}
         Select ``"delta"`` for Γ_δ or ``"alpha"`` for Γ_α.
-"""
-        + doc_bounce.split("    Parameters\n    ----------\n", maxsplit=1)[1]
-        + """
+""")
+        + "\n"
+        + doc_bounce.split("Parameters\n----------\n", maxsplit=1)[1]
+        + "\n"
+        + _clean_doc("""
     gamma_threshold : float
         Threshold for superbanana classification. Must be in ``(0,1)``.
         Default is 0.2.
-        """.rstrip()
+        """)
         + collect_docs(
             target_default="``target=0``.",
             bounds_default="``target=0``.",

desc/objectives/linear_objectives.py

@@ -24,7 +24,7 @@
 from desc.utils import broadcast_tree, errorif, setdefault
 
 from .normalization import compute_scaling_factors
-from .objective_funs import _Objective, collect_docs
+from .objective_funs import _clean_doc, _Objective, collect_docs
 
 
 # TODO (#1391): get rid of this class and inherit from FixParameters instead?
@@ -275,7 +275,7 @@ class ShareParameters(_Objective):
             "weight": "",
         }
     )
-    __doc__ += """
+    __doc__ += "\n\n" + _clean_doc("""
     Examples
     --------
     .. code-block:: python
@@ -319,7 +319,7 @@ class ShareParameters(_Objective):
         ]
         obj=ShareParameters([full_coilset, coilset2], params=params)
 
-    """
+    """)
     _scalar = False
     _linear = True
     _fixed = False

desc/objectives/objective_funs.py

@@ -2,6 +2,7 @@
 
 import functools
 from abc import ABC, abstractmethod
+from inspect import cleandoc
 
 import numpy as np
 
@@ -33,6 +34,12 @@
     warnif,
 )
 
+
+def _clean_doc(doc):
+    """Return a docstring fragment formatted for concatenation."""
+    return cleandoc(doc).rstrip()
+
+
 doc_target = """
     target : {float, ndarray}, optional
         Target value(s) of the objective. Only used if ``bounds`` is ``None``.
@@ -131,7 +138,7 @@
     "jac_chunk_size": doc_jac_chunk_size,
 }
 
-doc_bounce = """
+doc_bounce = "\n\n" + _clean_doc("""
     Notes
     -----
     Developer notes: Performance will improve significantly by resolving GitHub issues:
@@ -217,13 +224,11 @@
         instead of Chebyshev series. Default is ``True``. It can be preferable
         to set to ``False`` on equilibria with high ``NFP``, (such cases make
         smaller ``Y_B`` feasible), or on GPUs where eigenvalue solves are fast.
-    """.rstrip()
+    """)
 
 
-# Note: If we ever switch to Python 3.13 for building the docs, there will probably
-# be some errors since 3.13 changed how tabs are handled in docstrings. This can be
-# resolved by deleting the tabs in the collected docstring above and the ones
-# that are defined in objectives. Check `test_objective_docstring`.
+# Generated fragments are concatenated into class docstrings after Python has already
+# applied normal docstring cleaning, so keep them explicitly dedented here.
 def collect_docs(
     overwrite=None,
     target_default="",
@@ -265,7 +270,7 @@ def collect_docs(
         String of default parameters for the docstring.
 
     """
-    doc_params = ""
+    doc_params = []
 
     # Copy to allow for objective-specific updates to docs
     docs_obj = docs.copy()
@@ -280,39 +285,34 @@ def collect_docs(
 
     for key in docs_obj.keys():
         if overwrite is not None and key in overwrite.keys():
-            doc_params += overwrite[key].rstrip()
+            doc = _clean_doc(overwrite[key])
+            if doc:
+                doc_params.append(doc)
         else:
+            doc = _clean_doc(docs_obj[key])
             if key == "target":
-                target = ""
                 if target_default != "":
-                    target += " Defaults to " + target_default
-                doc_params += docs_obj[key].rstrip() + target
+                    doc += " Defaults to " + target_default
+                doc_params.append(doc)
             elif key == "bounds" and bounds_default != "":
-                doc_params = (
-                    doc_params
-                    + docs_obj[key].rstrip()
-                    + " Defaults to "
-                    + bounds_default
-                )
+                doc += " Defaults to " + bounds_default
+                doc_params.append(doc)
             elif key == "loss_function":
-                loss = ""
                 if loss_detail is not None:
-                    loss += loss_detail
-                doc_params += docs_obj[key].rstrip() + loss
+                    doc += loss_detail
+                doc_params.append(doc)
             elif key == "normalize":
-                norm = ""
                 if normalize_detail is not None:
-                    norm += normalize_detail
-                doc_params += docs_obj[key].rstrip() + norm
+                    doc += normalize_detail
+                doc_params.append(doc)
             elif key == "normalize_target":
-                norm_target = ""
                 if normalize_target_detail is not None:
-                    norm_target = normalize_target_detail
-                doc_params += docs_obj[key].rstrip() + norm_target
+                    doc += normalize_target_detail
+                doc_params.append(doc)
             else:
-                doc_params += docs_obj[key].rstrip()
+                doc_params.append(doc)
 
-    return doc_params
+    return "\n" + "\n".join(doc_params)
 
 
 class ObjectiveFunction(IOAble):
@@ -1927,7 +1927,7 @@ def things(self, new):
         self._built = False
 
 
-_Objective.__doc__ += "".join(value.rstrip("\n") for value in docs.values())
+_Objective.__doc__ += collect_docs()
 
 # local functions assigned as attributes aren't hashable so they cause stuff to
 # recompile, so instead we define a hashable class to do the same thing.

docs/conf.py

@@ -75,6 +75,9 @@
 autosummary_generate_overwrite = True
 # temporary fix to ignore errors raised in notebooks
 nbsphinx_allow_errors = True
+# Sphinx 9 cross-references short API parameter names such as ``M``, ``sym``,
+# and ``num_nodes`` to every matching Python object in generated autosummary pages.
+suppress_warnings = ["ref.python"]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]

tests/test_objective_funs.py

@@ -6,12 +6,11 @@
 This module primarily tests the constructing/building/calling methods.
 """
 
-import platform
 import warnings
+from inspect import cleandoc
 
 import numpy as np
 import pytest
-from packaging.version import Version
 from qsc import Qsc
 from scipy.constants import elementary_charge, mu_0
 
@@ -4385,25 +4384,16 @@ def test_objective_print_widths():
 @pytest.mark.unit
 def test_objective_docstring():
     """Test that the objective docstring and collect_docs are consistent."""
-    objective_docs = _Objective.__doc__.rstrip()
-    if Version(platform.python_version()) >= Version("3.13"):
-        doc_header = (
-            "Objective (or constraint) used in the optimization of an Equilibrium.\n\n"
-            + "Parameters\n"
-            + "----------\n"
-            + "things : Optimizable or tuple/list of Optimizable\n"
-            + "    Objects that will be optimized to satisfy the Objective.\n"
-        )
-    else:
-        doc_header = (
-            "Objective (or constraint) used in the optimization of an Equilibrium.\n\n"
-            + "    Parameters\n"
-            + "    ----------\n"
-            + "    things : Optimizable or tuple/list of Optimizable\n"
-            + "        Objects that will be optimized to satisfy the Objective.\n"
-        )
+    objective_docs = cleandoc(_Objective.__doc__).rstrip()
+    doc_header = (
+        "Objective (or constraint) used in the optimization of an Equilibrium.\n\n"
+        + "Parameters\n"
+        + "----------\n"
+        + "things : Optimizable or tuple/list of Optimizable\n"
+        + "    Objects that will be optimized to satisfy the Objective.\n"
+    )
     collected_docs = collect_docs().strip()
-    collected_docs = doc_header + "    " + collected_docs
+    collected_docs = doc_header + collected_docs
 
     assert objective_docs == collected_docs