CAGradWeighting has no docstring, so its doc page is empty

CAGradWeighting defines its _REQUIRED_DEPS and _INSTALL_HINT class attributes before its docstring. As a result, the string literal is just an expression statement and not the class docstring:

TorchJD/src/torchjd/aggregation/_cagrad.py

Lines 21 to 38 in 9ba45e3

    
           class CAGradWeighting(_WithOptionalDeps, _GramianWeighting, _NonDifferentiable): 
        
               _REQUIRED_DEPS = ["numpy", "cvxpy", "clarabel"] 
        
               _INSTALL_HINT = 'Install them with: pip install "torchjd[cagrad]"' 
        
               """ 
        
               :class:`~torchjd.aggregation.Weighting` [:class:`~torchjd.linalg.PSDMatrix`] 
        
               giving the weights of :class:`~torchjd.aggregation.CAGrad`. 
        
               :param c: The scale of the radius of the ball constraint. 
        
               :param norm_eps: A small value to avoid division by zero when normalizing. 
        
               .. note:: 
        
                   This implementation differs from the `official implementations 
        
                   <https://github.com/Cranial-XIX/CAGrad/>`_ in the way the underlying optimization problem is 
        
                   solved. This uses the `CLARABEL <https://oxfordcontrol.github.io/ClarabelDocs/stable/>`_ 
        
                   solver of `cvxpy <https://www.cvxpy.org/index.html>`_ rather than the `scipy.minimize 
        
                   <https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.minimize.html>`_ 
        
                   function. 
        
               """

So CAGradWeighting.__doc__ is None, and on the CAGrad doc page, CAGradWeighting only shows its signature: there's no description, and c and norm_eps are not documented.

>>> from torchjd.aggregation import CAGradWeighting
>>> CAGradWeighting.__doc__ is None
True

The private _NashMTLWeighting has the same problem (

TorchJD/src/torchjd/aggregation/_nash_mtl.py

Lines 24 to 46 in 9ba45e3

    
           class _NashMTLWeighting(_WithOptionalDeps, _MatrixWeighting, Stateful, _NonDifferentiable): 
        
               _REQUIRED_DEPS = ["numpy", "cvxpy", "ecos"] 
        
               _INSTALL_HINT = 'Install them with: pip install "torchjd[nash_mtl]"' 
        
               """ 
        
               :class:`~torchjd.Stateful` 
        
               :class:`~torchjd.aggregation.Weighting` [:class:`~torchjd.linalg.Matrix`] that 
        
               extracts weights using the step decision of Algorithm 1 of `Multi-Task Learning as a Bargaining 
        
               Game <https://arxiv.org/pdf/2202.01017.pdf>`_. 
        
               :param n_tasks: The number of tasks, corresponding to the number of rows in the provided 
        
                   matrices. 
        
               :param max_norm: Maximum value of the norm of :math:`J^T w`. A value of ``0`` disables the 
        
                   norm clipping. 
        
               :param update_weights_every: A parameter determining how often the actual weighting should be 
        
                   performed. A larger value means that the same weights will be re-used for more calls to the 
        
                   weighting. 
        
               :param optim_niter: The number of iterations of the underlying optimization process. 
        
               .. note:: 
        
                   Changing any of these parameters after instantiation does not automatically reset the 
        
                   internal state. Call :meth:`reset` if needed (especially after changing ``n_tasks``, which 
        
                   affects the shape of the cached state). 
        
               """

). It has no visible effect, since that class isn't documented, but it's worth fixing at the same time.

Suggested fix

In both classes, move the docstring above _REQUIRED_DEPS and _INSTALL_HINT, like in FairGradWeighting (

TorchJD/src/torchjd/aggregation/_fairgrad.py

Lines 24 to 46 in 9ba45e3

    
           class FairGradWeighting(_WithOptionalDeps, _GramianWeighting, _NonDifferentiable): 
        
               r""" 
        
               :class:`~torchjd.aggregation.Weighting` [:class:`~torchjd.linalg.PSDMatrix`] giving the 
        
               weights of :class:`~torchjd.aggregation.FairGrad`, as defined in Equation 4 of `Fair Resource 
        
               Allocation in Multi-Task Learning <https://arxiv.org/pdf/2402.15638>`_. 
        
               :param alpha: The parameter controlling the type of fairness in the alpha-fairness 
        
                   formulation. 
        
               :param max_iters: The maximum number of iterations of the optimization loop. If set to None, 
        
                   the default value of ``scipy.optimize.least_squares`` (``100 * m``) will be used. 
        
               .. note:: 
        
                   This implementation was adapted from the `official implementation 
        
                   <https://github.com/OptMN-Lab/fairgrad/blob/main/methods/weight_methods.py#L811-L825>`_. 
        
               .. note:: 
        
                   This aggregator requires optional dependencies. When they are not installed, instantiating 
        
                   it raises an :class:`ImportError` with installation instructions. 
        
                   To install them, use ``pip install "torchjd[fairgrad]"``. 
        
               """ 
        
               _REQUIRED_DEPS = ["numpy", "scipy"] 
        
               _INSTALL_HINT = 'Install it with: pip install "torchjd[fairgrad]"'

).

Checklist

Move the docstrings in src/torchjd/aggregation/_cagrad.py and src/torchjd/aggregation/_nash_mtl.py.
(Optional) Add a test checking that every public class of torchjd.aggregation has its own docstring, e.g. "__doc__" in cls.__dict__ and cls.__doc__, so that this can't happen again.
Build the docs (uv run make clean -C docs; uv run make html -C docs) and check that docs/build/html/docs/aggregation/cagrad.html shows the description of CAGradWeighting.

See CONTRIBUTING.md to set up the development environment.

Closed already.

Navigation Menu

Repository navigation

`CAGradWeighting` has no docstring, so its doc page is empty #807

Suggested fix

Checklist

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

	class CAGradWeighting(_WithOptionalDeps, _GramianWeighting, _NonDifferentiable):
	_REQUIRED_DEPS = ["numpy", "cvxpy", "clarabel"]
	_INSTALL_HINT = 'Install them with: pip install "torchjd[cagrad]"'
	"""
	:class:`~torchjd.aggregation.Weighting` [:class:`~torchjd.linalg.PSDMatrix`]
	giving the weights of :class:`~torchjd.aggregation.CAGrad`.

	:param c: The scale of the radius of the ball constraint.
	:param norm_eps: A small value to avoid division by zero when normalizing.

	.. note::
	This implementation differs from the `official implementations
	<https://github.com/Cranial-XIX/CAGrad/>`_ in the way the underlying optimization problem is
	solved. This uses the `CLARABEL <https://oxfordcontrol.github.io/ClarabelDocs/stable/>`_
	solver of `cvxpy <https://www.cvxpy.org/index.html>`_ rather than the `scipy.minimize
	<https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.minimize.html>`_
	function.
	"""

	class _NashMTLWeighting(_WithOptionalDeps, _MatrixWeighting, Stateful, _NonDifferentiable):
	_REQUIRED_DEPS = ["numpy", "cvxpy", "ecos"]
	_INSTALL_HINT = 'Install them with: pip install "torchjd[nash_mtl]"'
	"""
	:class:`~torchjd.Stateful`
	:class:`~torchjd.aggregation.Weighting` [:class:`~torchjd.linalg.Matrix`] that
	extracts weights using the step decision of Algorithm 1 of `Multi-Task Learning as a Bargaining
	Game <https://arxiv.org/pdf/2202.01017.pdf>`_.

	:param n_tasks: The number of tasks, corresponding to the number of rows in the provided
	matrices.
	:param max_norm: Maximum value of the norm of :math:`J^T w`. A value of ``0`` disables the
	norm clipping.
	:param update_weights_every: A parameter determining how often the actual weighting should be
	performed. A larger value means that the same weights will be re-used for more calls to the
	weighting.
	:param optim_niter: The number of iterations of the underlying optimization process.

	.. note::
	Changing any of these parameters after instantiation does not automatically reset the
	internal state. Call :meth:`reset` if needed (especially after changing ``n_tasks``, which
	affects the shape of the cached state).
	"""

	class FairGradWeighting(_WithOptionalDeps, _GramianWeighting, _NonDifferentiable):
	r"""
	:class:`~torchjd.aggregation.Weighting` [:class:`~torchjd.linalg.PSDMatrix`] giving the
	weights of :class:`~torchjd.aggregation.FairGrad`, as defined in Equation 4 of `Fair Resource
	Allocation in Multi-Task Learning <https://arxiv.org/pdf/2402.15638>`_.

	:param alpha: The parameter controlling the type of fairness in the alpha-fairness
	formulation.
	:param max_iters: The maximum number of iterations of the optimization loop. If set to None,
	the default value of ``scipy.optimize.least_squares`` (``100 * m``) will be used.

	.. note::
	This implementation was adapted from the `official implementation
	<https://github.com/OptMN-Lab/fairgrad/blob/main/methods/weight_methods.py#L811-L825>`_.

	.. note::
	This aggregator requires optional dependencies. When they are not installed, instantiating
	it raises an :class:`ImportError` with installation instructions.
	To install them, use ``pip install "torchjd[fairgrad]"``.
	"""

	_REQUIRED_DEPS = ["numpy", "scipy"]
	_INSTALL_HINT = 'Install it with: pip install "torchjd[fairgrad]"'

CAGradWeighting has no docstring, so its doc page is empty #807

Description

Suggested fix

Checklist

Activity

adityawaghamare commented on Oct 8, 2026

ValerianRey commented on Oct 8, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

`CAGradWeighting` has no docstring, so its doc page is empty #807