Uploaded image for project: 'Data Management'
  1. Data Management
  2. DM-17064

Support PEP 484 type annotations for populating API reference

    Details

    • Type: Story
    • Status: To Do
    • Resolution: Unresolved
    • Fix Version/s: None
    • Component/s: documenteer
    • Labels:
      None

      Description

      Instead of writing type information in docstrings, we can use type annotations (which are inherently testable).

      There are two Sphinx extensions that support PEP 484 type hints for functions parameters:

      Although I won't confirm it as the optimal choice, https://github.com/agronholm/sphinx-autodoc-typehints seems to be a more active project.

      Based on my reading, it seems that these projects are already compatible with tools that parse docstrings. The key is to add the sphinx_autodoc_typehints extension after autodoc, but before a parser like numpydoc or Napoleon.

      I haven't yet confirmed that numpydoc works, though it should given that Napoleon does work.

        Attachments

          Container Issues

            Issue Links

              Activity

                People

                • Assignee:
                  jsick Jonathan Sick
                  Reporter:
                  jsick Jonathan Sick
                  Watchers:
                  Jonathan Sick, Krzysztof Findeisen, Tim Jenness
                • Votes:
                  0 Vote for this issue
                  Watchers:
                  3 Start watching this issue

                  Dates

                  • Created:
                    Updated:

                    Summary Panel