truenas
NAS-135866 / 25.10 / Remove unwanted newlines in API docs
The following field docstring:
field: int
"""Just a
chill guy."""
produces the field description "Just a\nchill guy." which isn't pleasant to look at in the API docs.
Rejected Solution
Parse double newlines as single newlines and single newlines like in the example above as spaces.
Using this implicit docstring parsing makes some formatting unintuitive or unwieldy, particularly when using reST in API docstrings.
Solution
Instead, we need to be intentional when writing API docstrings by ending line wraps with backslashes to remove the newline. So the above example would become:
field: int
"""Just a \
chill guy."""
and would parse to "Just a chill guy." as intended.
Proposed Standards
Now that our API docs are provided to the public, we need to establish some formatting guidelines. The changes made in this PR include:
- Only use triple quotation marks
"""for API docstrings as per PEP-257. Triple apostrophes''', single quotation marks", and single apostrophes'should not be used to denote docstrings. - API docstrings should begin with a capital letter unless the first word is a variable name or other identifier.
- API docstrings all must end with a period.
Is this PR supposed to include the actual fix for the issue? I only see type hint improvements and comments change.
Is this PR supposed to include the actual fix for the issue? I only see type hint improvements and comments change.
@themylogin The main solution here is adding backslashes to docstrings that wrap to the next line to remove the unwanted newline. This way is better and more intentional than what I originally had because we don't always want to remove newlines.
I am not a fan of this approach, we'll be forgetting to add \ all the time. @yocalebo I'll let you decide.
The API docs are publicly facing now, so better care will just have to be taken. Here's a concrete example of where the original solution is not ideal.
Here's an unordered list in RST normally:
* this is
* a list
* with a nested list
* and some subitems
* and here the parent list continues
If each double newline is parsed into a single newline, here's how we would have to write it in the docstring:
"""
* this is
* a list
* with a nested list
* and some subitems
* and here the parent list continues
"""
- Added a new flake8 plugin flake8-literal which can be used to standardize string literals across the repository. For now, just using it to enforce the proposed standard of using
"""for docstrings. It also adds checks for raw and formatted strings. - Added a CI test to loosely check capitalization, punctuation, and line wraps in API docstrings. It's neither ideal nor optimal, but it will help enforce standards moving forward.
- Fixed up the docstrings that have been added/changed since this PR was created.
This PR has been merged and conversations have been locked. If you would like to discuss more about this issue please use our forums or raise a Jira ticket.