improve docs for FieldValidator objects #4509
Conversation
chrishavlin
added
docs
refactor
yt/fields/derived_field.py
Outdated
| If *parameter_values* is supplied, this will also ensure that the field | ||
| Parameters | ||
| ---------- | ||
| parameters: Union[str, Iterable[str] |
There was a problem hiding this comment.
We usually don't use type annotation syntax in docstrings. In particular Union and Optional should be avoided there because they are not needed since Python 3.10 (these annotations will be simplified with ruff (pyupgrade) when Python 3.9 is dropped).
There was a problem hiding this comment.
removed all the Union and Optional occurrences. left the iterable though? Should I remove that too? it is nice to note that it could be a str or any iterable with str's. but I could remove the Iterable and rephrase the description
yt/fields/derived_field.py
Outdated
| @@ -589,3 +625,14 @@ def __call__(self, data): | |||
| if getattr(data, "_type_name", None) == "grid": | |||
| return True | |||
| raise NeedsOriginalGrid() | |||
|
|
|||
|
|
|||
| def _set_field_validator_base_docstring(): | |||
There was a problem hiding this comment.
This would be suited for FieldValidator.__init_subclass__
There was a problem hiding this comment.
good idea! i'll move it and refactor a bit as needed.
There was a problem hiding this comment.
now in __init_subclass__
Co-authored-by: Clément Robert <cr52@protonmail.com>
Co-authored-by: Clément Robert <cr52@protonmail.com>
This PR:
FieldValidatorsubclasses up out of their__init__methods so they get picked up by the docs buildFieldValidatordocstring to point to the available subclasses.Background: I was working using one of the
FieldValidatorand noticed that all the docstrings here were empty despite their presence in the__init__methods. Thought it'd be useful to bump those up so we catch them during the docs build... and then I made an effort to improve the docstrings.I'm not super familiar with the different validators, so it's possible I misinterpreted the arguments (both the descriptions and any typing I added).
Also, this includes one small code refactoring as well as a little function to dynamically update the
FieldValidatordocstring -- I'm happy to remove those if it's better to simplify this PR.