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

Use PEP-484 type hints instead of docstring types #212

Open
goodmami opened this issue Apr 18, 2019 · 2 comments
Open

Use PEP-484 type hints instead of docstring types #212

goodmami opened this issue Apr 18, 2019 · 2 comments
Labels
maintenance improving code quality; not features or bugs

Comments

@goodmami
Copy link
Member

The napoleon extension to Sphinx (which we use for documentation) accepts PEP-484 type hints as well as types in the docstrings. E.g., these are the same:

def foo(a):
    """
    foo the a

    Args:
        a (int): a bar
    """
    return a * 2

def foo(a: int):
    """
    foo the a

    Args:
        a: a bar
    """
    return a * 2

The type hints in the latter can also be used by static analysis tools for type checking, and maybe other things in the future. We should aim to (maybe gradually) incorporate type hints wherever applicable throughout the PyDelphin codebase.

@goodmami goodmami added the maintenance improving code quality; not features or bugs label Apr 18, 2019
@goodmami
Copy link
Member Author

It seems the Napoleon support for type hints is not great. There's a third party module: https://github.com/agronholm/sphinx-autodoc-typehints

But the rendering, while informative, isn't so pretty.

Nevertheless, the type hints are probably a good way to go, but we might have to customize some CSS to make it more legible.

goodmami added a commit that referenced this issue Apr 18, 2019
@goodmami goodmami added this to the v1.7.0 milestone Jul 17, 2022
@goodmami goodmami removed this from the v1.7.0 milestone Oct 14, 2022
@goodmami
Copy link
Member Author

This will be a huge effort that I'm not prepared to do right now, so I'm removing it from 1.7.0.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
maintenance improving code quality; not features or bugs
Projects
None yet
Development

No branches or pull requests

1 participant