5

I'm looking for a tool that adds the type annotation that are already added in a function to the docstring generated by PyCharm.

I have been following this issue on JetBrains for a long time and no progress seem to be made on this ticket yet.

I saw this article as well but it seems too specific and only works with google docstrings.

I have checked out this package on PyPI but this does the opposite of what I need. What I need is to add the type hints provided in the argument to the docstring and not the opposite.

This might be related to How to make PyCharm get type hints from function definition and populate type values in docstrings?, but I just need a general purpose solution, or at least one that works with Numpy docstring or reStructuredText and maybe play nicely with PyCharm.

I just see myself coming back to researching this thing in the hopes of getting something but couldn't find what I needed. What tools would work for this?

Alex Waygood
  • 6,304
  • 3
  • 24
  • 46
Ashley Alfredssons
  • 109
  • 1
  • 6
  • 1
    Asking for curiosity: what is the point to document type hints again in the dostring, as automated API document generator can read them directly from the typehints? – Mikko Ohtamaa Sep 23 '21 at 09:24
  • @MikkoOhtamaa interesting. May I ask if you can let me know about one of the automated API document generator that can automatically incorporate type hints into the document page with someway of linking them to the docs of the original type? so if i added a type hint `foo(a: bar) -> bool:` it will give some sort of a link to the `bar` docs. my goal from adding types to the docstring is for this linking feature, and the type hints in the functions are just for mypy and easier debugging with the IDE. – Ashley Alfredssons Sep 23 '21 at 09:46
  • 1
    Sphinx should already pull the types from the annotations. PyCharm itself also seems to properly use annotations in its help popups. In fact I would recommend *not* to duplicate information by putting it into the docstring as well. – MisterMiyagi Sep 23 '21 at 09:47
  • @MisterMiyagi thank you for this info, i will look into sphinx and try to see if it will give me what I need, yeah duplicating info seems not useful if you will type it manually twice. – Ashley Alfredssons Sep 23 '21 at 09:57

1 Answers1

4

When I was searching few months ago, I couldn't find any usable solution for this. Right now, I am using VS Code with this extension which gives nice Docstring:

def foo(a: int, b: str) -> bool:
    """[summary]

    Args:
        a (int): [description]
        b (str): [description]

    Returns:
        bool: [description]
    """
zweack
  • 141
  • 1
  • 10
  • Does the extension work if you have you have an already annotated function for example, `foo(a: int, b: str) -> bool:` will it generate the template for the args and returns with the correct types? the extension seems cool although the number of issues in its repo is not assuring. I might switch to VS code if it means better documentation experience – Ashley Alfredssons Sep 23 '21 at 09:40
  • Yes, once you hit `"""`, it will generate the template for the args and returns with the correct types. I generally don't care about number of issues, but it doesn't have any new commits since March which is not assuring. – zweack Sep 23 '21 at 10:44