autoDocstring
autoDocstring copied to clipboard
NilsJPWerner
Optionally write types in docstring - PEP 484
Functions implementing PEP 484 annotate arguments' type in their signature. It feels a bit redundant to mention args type again in docstrings.
According to at least Sphinx Napoleon's doc the following Google-style docstring is acceptable:
def function_with_pep484_type_annotations(param1: int, param2: str) -> bool:
"""Example function with PEP 484 type annotations.
Args:
param1: The first parameter.
param2: The second parameter.
Returns:
The return value. True for success, False otherwise.
"""
Would it be possible to add logic to write docstring without types if they are mentioned in functions' signature? I imagine some users would like to keep having types mentioned in docstrings so perhaps a setting toggling this behavior could be a good idea?
Thanks
You could define your own docstring format that omits the types. You can take the google style template and remove all the {{typePlaceholder}} tags and then use that as your custom docstring format.
Yes that's what I did, I just thought it could be of interest to some other users. Have it directly in your lib would prevent to create individual custom templates just to remove the types.
Besides, a custom docstring templates would disable or enable types in a binary fashion. What I suggest is to write types only if they are not provided as annotations, allowing usage of hybrid function signatures.
If you feel this is not much of interest feel free to close, and thank you for providing this lib! :+1:
Also support this! Ideally this should be triggered when you have a setting for Google format like removeTypeFromPep484Function on and your function contains a type hint.
Support in this. I even think this should be the default. For documentation it is clearer and easier to maintaint.
@NumberPiOso I think the default should be what the documentation's style own guidelines propose because I think now this is very down to personal opinion. I can think of a lot of cases where although you did type hint you might still want to give a more verbose explanation of what is being returned. Do you buy that?
I do not really see it, but I guess it is true that all this is about personal opinions. I tried to look what is the recomendation with type annotation in the style guidelines and I did not have any luck. Sphinx examples were the closest I managed to find. Would you please show some references about the Numpy or Google guidelines with type annotations?
Having an additional template like google-pep-484 would be nice. Looking at the current Google styleguide they omit the types from the docstring as they are clear via the use of type hints in the signature:
def fetch_smalltable_rows(table_handle: smalltable.Table,
keys: Sequence[Union[bytes, str]],
require_all_keys: bool = False,
) -> Mapping[bytes, Tuple[str]]:
"""Fetches rows from a Smalltable.
Retrieves rows pertaining to the given keys from the Table instance
represented by table_handle. String keys will be UTF-8 encoded.
Args:
table_handle: An open smalltable.Table instance.
keys: A sequence of strings representing the key of each table
row to fetch. String keys will be UTF-8 encoded.
require_all_keys: Optional; If require_all_keys is True only
rows with values set for all keys will be returned.
Returns:
A dict mapping keys to the corresponding table row data
fetched. Each row is represented as a tuple of strings. For
example:
{b'Serak': ('Rigel VII', 'Preparer'),
b'Zim': ('Irk', 'Invader'),
b'Lrrr': ('Omicron Persei 8', 'Emperor')}
Returned keys are always bytes. If a key from the keys argument is
missing from the dictionary, then that row was not found in the
table (and require_all_keys must have been False).
Raises:
IOError: An error occurred accessing the smalltable.
"""
+1 from me as well.
It's cumbersome and unnecessary to keep the docstring type hints in sync with the function signature. And Sphinx-plugins like sphinx_autodoc_typehints will happily read the types from the function signature.
FYI @NilsJPWerner I made PR to add this template as a new template (google-notypes) in the extension's settings menu. Let me know what you think. 😊
