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.

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

Format Solver.py docstring to match numpy convention #17

Merged
merged 3 commits into from
Feb 23, 2023
Merged

Format Solver.py docstring to match numpy convention #17

merged 3 commits into from
Feb 23, 2023

Conversation

mscheltienne
Copy link

@mscheltienne mscheltienne commented Feb 23, 2023

For starter, a couple more changes following #16. I did end up mixing up slightly files from #10 and from #16, leading to some typos fixed here:

  • line-length increased from 79 characters to the default 88. black run across the code-base again, modifying all the files to the correct line-length.
  • import_optional_dependency which I did setup.. and then reverted by mistake when I reverted all the changes to the codebase added in Updated packaging format #10. It is now correctly used to manage the optional dependency sksparse, raising an error message with the library name on pip and conda if use_cholmod is True and the dep. is missing.

Those fixes following #16 done, the main focus of this PR was documentation. I reformatted the docstring from Solver.py to match the numpy convention:

def foo(a: int, b: float) -> float:
    """Summary line in imperative mood ending with a dot.

    Short optional description.

    Parameters
    ----------
    a : int
        Parameter 'a' description.
    b : float
        Parameter 'b' description
    
    Returns
    -------
    x : float
        Return 'x' description
    
    Notes
    -----
    Additional notes and information.
    """
    x = a + b
    return x

The full convention can be found on the numpydoc website. One good aspect about this convention is that it is well understood by sphinx, used to build a documentation website for your projects.
Talking about sphinx, you'll notice the use of double backticks and of single backticks in the docstrings. Double backticks are used for formatting, usually of variables while single backticks are used for cross-referencing. e.g. ~lapy.TetMesh encapsulated in single backticks (hard to render on GitHub..) will yield a link to the documentation of the class TetMesh.
One more point, another good practice to have is to describe the shape of fix length arrays, e.g. numpy arrays or tuples. For instance, array of shape (2,) or tuple of shape (n_channels, ) or array of shape (n_channels, n_samples).

Anyway, I've done it for the Solver.py file and class, which you can now use as a template for the rest, but I will not do it for the others. I am not super familiar with the mathematics used behind, and I am not the best person to document those classes and functions.
The Solver.py file now follows the numpy convention, and pydocstyle lapy/Sovler.py does not raise any additional warnings. If you apply this convention to the other classes, we can add a documentation build workflow to automatically build and deploy the package documentation. Here is an example workflow with the associated website (sandbox repository I use for testing). Note that sphinx supports module for bibliography and for mathematical expressions ;)

@m-reuter m-reuter merged commit 5316fab into Deep-MI:master Feb 23, 2023
@mscheltienne mscheltienne deleted the docstrings branch February 23, 2023 16:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants