Skip to content

Comments

docs: Remove duplicate type hints in docstrings and annotations#2483

Draft
MortGron wants to merge 1 commit intopysdk-release-v8from
remove-duplicate-type-hints
Draft

docs: Remove duplicate type hints in docstrings and annotations#2483
MortGron wants to merge 1 commit intopysdk-release-v8from
remove-duplicate-type-hints

Conversation

@MortGron
Copy link
Contributor

Description

The duplication of type hints in both docstring and as annotations makes the docstrings unnecessarily hard to read as a developer. It is possible to remove type hints in the docstrings without changing the structure of the documentation. This PR removes all type hints from the docstrings, but enables a Sphinx extension to keep the type hints in the documentation.

Current documentation:

image

New documentation:

image

A few points to discuss:

  • Should it still be allowed to provide type hints in the docstrings? It might make sense for very long type hints to have a custom type hint instead
  • Is the change in documentation look accepptable? All type hints are now stylized as inline code in the documentation, which in my opinion is slightly less readable than how it was.

Checklist:

  • Tests added/updated.
  • Documentation updated. Documentation is generated from docstrings - these must be updated according to your change.
    If a new method has been added it should be referenced in cognite.rst in order to generate docs based on its docstring.
  • The PR title follows the Conventional Commit spec.

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.

1 participant