Docs: render autodoc & typehints in the API documentation #359
Conversation
efel/pyfeatures/pyfeatures.py
Outdated
| warnings.warn( | ||
| "Error while calculating feature %s: %s" % | ||
| (featureName, cppcore.getgError()), | ||
| f"Error while calculating {feature_name}, {cppcore.getgError()}", | ||
| RuntimeWarning) | ||
| return None | ||
| else: |
There was a problem hiding this comment.
can remove the else: here
There was a problem hiding this comment.
Coming with the next push.
| Seeks for the stim_start and stim_end parameters inside the Neo data. | ||
|
|
||
| Args: | ||
| blocks (Neo object blocks): Description of what blocks represents. |
There was a problem hiding this comment.
Could you describe what blocks represent here?
There was a problem hiding this comment.
This function is written 7 year ago using the Neo package at that time. There is an internal efel ticket to update the usage to the recent one. There is a high chance that this function will be written in a much simpler way. Shall we update the args once that ticket it through?
There was a problem hiding this comment.
Alright, sure, no problem
There was a problem hiding this comment.
Noted, I will make the update when I work on this ticket
efel/io.py
Outdated
| The returned object is presented like this : | ||
| returned object : [Segments_1, Segments_2, ..., Segments_n] | ||
| Segments_1 = [Traces_1, Traces_2, ..., Traces_n] | ||
| Seeks for the stim_start and stim_end parameters inside the Neo data. |
There was a problem hiding this comment.
It looks like you just copy/pasted docstring from previous function here. Could you correct it?
There was a problem hiding this comment.
Oh good that you noticed. This docstring and the one above were both raising sphinx errors, I must have copied the wrong one.
efel/api.py
Outdated
| @@ -1,10 +1,10 @@ | |||
| from __future__ import annotations | |||
There was a problem hiding this comment.
why put these import statements above the docstring?
There was a problem hiding this comment.
It is being updated in the next push
efel/api.py
Outdated
| path to the location of a Dependency file | ||
| """ | ||
| eFEL uses 'Dependency' files to let the user define versions of features to use. | ||
| The installation directory of the eFEL contains a default 'DependencyV5.txt' file. |
efel/api.py
Outdated
| True if feature_name exists, otherwise False | ||
| """ | ||
| def feature_name_exists(feature_name: str) -> bool: | ||
| """Returns True if the feature name exists in the eFEL, False otherwise.""" |
There was a problem hiding this comment.
Coming with the next push...
efel/api.py
Outdated
| The value is None if an error occured during the | ||
| calculation of the feature. | ||
| Args: | ||
| traces: Every trace dict represent one trace. The dict should have the |
There was a problem hiding this comment.
typo: represent -> represents
efel/api.py
Outdated
| raise_warnings: Raise warning when efel c++ returns an error | ||
|
|
||
| Returns: | ||
| For every input trace a feature value dict is return (in |
There was a problem hiding this comment.
typo: return -> returned
efel/api.py
Outdated
| calculation of the feature, or if the feature value array | ||
| was empty. | ||
| Args: | ||
| traces: Every trace dict represent one trace. The dict should have the |
There was a problem hiding this comment.
typo: represent -> represents
efel/api.py
Outdated
| raise_warnings: Raise warning when efel c++ returns an error | ||
|
|
||
| Returns: | ||
| For every input trace a feature value dict is return (in |
There was a problem hiding this comment.
typo: is return -> is returned
|
@AurelienJaquier ah yes, mypy asked to handle the possible |
Description
Docs now show all of the public functions in the API. Before it was only listing their names.
Docs show the argument types and return types. API docs are type checked using type hints and a static type checker to ensure they are always up-to-date.
Docs show CHANGELOG.
A few fixes in the function/method docstrings.
Before
Only the function names and the first line of docstring are provided.
After
Not only the first line but the complete docstring get generated for each function. Return types and argument types are annotated using type hints (instead of using docstrings).
Checklist: