Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Clean docstrings of V2 #122

Open
36 tasks
NicolasGensollen opened this issue Feb 20, 2025 · 0 comments
Open
36 tasks

Clean docstrings of V2 #122

NicolasGensollen opened this issue Feb 20, 2025 · 0 comments

Comments

@NicolasGensollen
Copy link
Member

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 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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
1 participant
@NicolasGensollen