pydoclint supports three mainstream docstring styles: numpy, Google, and Sphinx. But there are some minor deviations from the standard style for practical reasons (such as unambiguity and speed).
Table of Contents
These styles specified in the numpydoc website are not accepted by pydoclint:
Parameters
----------
iterable : iterable object
shape : int or tuple of int
files : list of str
flag : int, optional
This is because these natural languages are inherently ambiguous, difficult to check, and difficult to keep consistent within a project.
Instead, pydoclint only accepts type hints that look identical to the function signature:
Parameters
----------
iterable : Iterable[int]
shape : int | tuple[int, ...]
files : list[str]
flag : int | None, default=None
These styles to specify default values are not accepted by pydoclint:
flag : int, optional
something: int, default 2
onething: bool, default: False
These are accepted:
flag : int | None, default=None
something: int, default=2
onething: bool, default=False
This would ensure that different code maintainers would write consistent style within the same project.
By default, pydoclint checks return type and yield type consistencies, and it also requires argument types in the docstring. In other words, by pydoclint’s default, this is an acceptable Google-style docstring:
"""
This is a function.
Args:
arg1 (int): Arg 1
arg2 (float): Arg 2
arg3 (Optional[Union[float, int, str]]): Arg 3
Returns:
int: Result
"""
However, this may not be the convention of a lot of Google-style docstring writers.
But do not worry: here are some config options to tweak:
--arg-type-hints-in-docstring: you can set it to False--check-return-types: you can set it to False--check-yield-types: you can set it to FalseHere are all the configurable options of pydoclint, and here is how to configure pydoclint.
These styles to specify default values are not accepted by pydoclint:
flag (int, optional): The flag. Defaults to 1
This is accepted:
flag (int, default=None): The flag
The official Sphinx documentation does not explicitly state this, so it is unclear what header to use to specify the type of what a function yields.
Many people use rtype, but the authors of pydoclint find it difficult to
differentiate the type of return value and the type of yield value.
Therefore, pydoclint expects the convention of ytype for yield types. This
is actually common practice, as evident from a code search on GitHub:
https://github.com/search?q=%3Aytype%3A+language%3APython&type=code&l=Python