Skip to content

Clean docstrings of V2

Objectives

As discussed in recent meetings, we need to take care of the docstrings of Leaspy V2. The goals are:

  • make sure the docstrings exist (at least for public objects)
  • make sure the docstrings are correctly formatted (Numpydoc style, cross-references etc...)
  • make sure the texts of the docstrings are correct and complete (sometimes they are out-of-sync with the code, sometimes they don't make any sense, sometimes they are pretty obscure...)
  • try to improve the docstrings as much as possible (add type hints, add references and so on)

Style and references

In terms of style, we use the Numpydoc style to write our docstrings, they should basically look like that:

def do_something(parameter1: int, parameter2: str = "all") -> float:
    """One line short description of what the function does.

    Eventually a more detailed explanation which can span multiple lines.

    Parameters
    ----------
    parameter1 : :obj:`int`
        Description of parameter1.

    parameter2 : :obj:`str`, optional
        Description of parameter2.
        Default="all".

    Returns
    -------
    :obj:`float` :
        Description of the return value.
    """
    ....

In docstrings it is possible to link other functions or classes of Leaspy by using the following syntax: :class:~leaspy.models.AbstractModel. You can take a look at MR !189 (merged) to see some examples.

Work organization

As discussed, we can share the load between us. I'm going to propose a split but we can re-organize things if some of you want to do more/less.

The idea would be to open small MR targeting a small number of files at the time. We could for example have one MR per bullet point if that makes sense.

leaspy.algo

leaspy.datasets

  • leaspy.datasets : @NicolasGensollen (It's more or less already done, I'll finish it if needed...)

leaspy.io

leaspy.models

leaspy.samplers

leaspy.utils

leaspy.variables