Skip to content
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

Update docs based on Python type hints #524

Merged
merged 3 commits into from
May 11, 2022
Merged

Conversation

cclauss
Copy link
Contributor

@cclauss cclauss commented May 11, 2022

It was quite easy to add https://pypi.org/project/sphinx-autodoc-typehints to docs/requirements.txt and then generate docs based on Python type hints that look like this:

Screenshot 2022-05-11 at 07 30 29


This enables us to remove a fair amount of repetitive (and somewhat erroneous) typing information from method docstrings. These lines can all be remove from docstrings: grep ":type " **/*.py and grep ":rtype:" **/*.py

@JustAnotherArchivist @maxz ... Might be of interest.

@cclauss cclauss changed the title DRAFT: Update docs based on Python type hints Update docs based on Python type hints May 11, 2022
@cclauss cclauss marked this pull request as ready for review May 11, 2022 05:42
@cclauss
Copy link
Contributor Author

cclauss commented May 11, 2022

  1. Change all occurrences of :rtype: to :returns:
  2. Delete lines that contain ":type " (only if the Python type hint is present).
  3. Change all occurrences of ": (optional) " with ": "
  4. Go back thru the :returns: and clean up any duplicate entries.

Copy link
Contributor

@maxz maxz left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice. I never particularly liked to also have to specify type information in the docstrings.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants