Format Solver.py docstring to match numpy convention #17
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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:
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 dependencysksparse
, raising an error message with the library name on pip and conda ifuse_cholmod
isTrue
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:The full convention can be found on the
numpydoc
website. One good aspect about this convention is that it is well understood bysphinx
, 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 classTetMesh
.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,)
ortuple of shape (n_channels, )
orarray 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 thenumpy
convention, andpydocstyle 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 thatsphinx
supports module for bibliography and for mathematical expressions ;)