-
Notifications
You must be signed in to change notification settings - Fork 224
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
TYP: Improve the doc style for type hints #2813
Conversation
02e0baf
to
cc6c461
Compare
pygmt/datasets/earth_relief.py
Outdated
@@ -4,6 +4,9 @@ | |||
|
|||
The grids are available in various resolutions. | |||
""" | |||
from collections.abc import Sequence |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Need to revert any changes in this file before merging.
pygmt/datasets/earth_relief.py
Outdated
region: Union[str, Sequence, None] = None, | ||
registration: Literal["gridline", "pixel", None] = None, | ||
data_source: Literal["igpp", "gebco", "gebcosi", "synbath"] = "igpp", |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I don't think it's possible.
pygmt/datasets/earth_relief.py
Outdated
registration=None, | ||
data_source="igpp", | ||
region: Union[str, Sequence, None] = None, | ||
registration: Literal["gridline", "pixel", None] = None, |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I feel the current doc style (style 4 in the above table) is the best one.
I agree that the signature of No 1 is too complicated. The highlighting of No 3 and No 4 is good, as it is consistent with the rest of the documentation.
Is it required to always give a default value? I am wondering if something like this can be a bit misleading (even though it is also given like this in the signature):
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is it required to always give a default value?
We don't have to give a default value, but I feel a default value in the function strings is good so that users don't have to go back to the function signature to know the default.
I am wondering if something like this can be a bit misleading (even though it is also given like this in the signature):
Yes, it's misleading. We can rephrase it to something like:
Default is
None
, which means"gridline"
for all resolutions except ...
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We don't have to give a default value, but I feel a default value in the function strings is good so that users don't have to go back to the function signature to know the default.
I also think it's good to have the default value in the function string. Just thought about not stating it for cases like above, but rephrasing the docstring should also prevent confusion.
In commit cc6c461, I added type hints to the
region
,registration
anddata_source
parameters and also remove the parameter types from docstrings (following this guide). Other parameters likeresolution
anduse_srtm
are not changed. So now this function has "partial" type hints support.This PR tries to find out the best style for API documentations.
Preview: https://pygmt-dev--2813.org.readthedocs.build/en/2813/api/generated/pygmt.datasets.load_earth_relief.html
str
) are a little distractiveI feel the current doc style (style 4 in the above table) is the best one. What do you think @GenericMappingTools/pygmt-maintainers?