[Waiting] Add docformatter

[ValerianRey]

Fixes #77

• Add docformatter pre-commit hook

Currently a bug in docformatter prevents us from using it.

TODO:

• Update rev of docformatter in .pre-commit-config.yaml whenever the bug is fixed and the fix is released. There is an open PR for this already.
• Run pdm run pre-commit run --all-files and commit the changes to apply the new formatting.

[ValerianRey]

This does not work satisfyingly: running pdm run pre-commit run --all-files will run docformatter on all files with the appropriate config (as expected) but because of a bug, we obtain the following change in cagrad.py:

    """
    :class:`~torchjd.aggregation.bases._Weighting` that extracts weights using the CAGrad algorithm,
    as defined in algorithm 1 of `Conflict-Averse Gradient Descent for Multi-task Learning
    <https://arxiv.org/pdf/2110.14048.pdf>`_.

    :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/>`_
    :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.
    """

(everything is messed up).
If we re-run the hooks on cagrad.py again, it messes it up even more.

[PierreQuinton]

that si annoying, is there another docformatter out there ?

[ValerianRey]

that si annoying, is there another docformatter out there ?

Probably, but I think this one is the most widely used. And apart from the bug I mentioned, it seemed to work really well. With the option force-wrap it breaks links, but I checked and sphinx still makes working links out of multi-line urls.

So I think we should just wait for the bug to be fixed.

[ValerianRey]

Still got a different bug after their fix:

    :param parallel_chunk_size: The number of scalars to differentiate simultaneously in the
        backward pass. If set to ``None``, all coordinates of ``tensors`` will be differentiated in
        parallel at once. If set to ``1``, all coordinates will be differentiated sequentially. A
        larger value results in faster differentiation, but also higher memory usage. Defaults to
        ``None``. .. admonition:: Example A usage example of ``mtl_backward`` is provided in
        :doc:`Multi-Task Learning (MTL) <../../examples/mtl>`.

in mtl_backward.py.

Let's give up on using docformatter.

Another problem is that there's currently no way to disable newlines after the first sentence of the docstring, leading to things like:

    """
    Transform that produces gradients filled with ones, for testing purposes.

    Note that it does the same thing as Init, but it does not depend on Init.
    """

in test_stack.py.

This behavior is quite standard though so debatable.