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 both autodoc and a preprocessor like numpydoc or Napoleon.

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

        Attachments

          Issue Links

            Activity

            Hide
            jsick Jonathan Sick added a comment -

            I added some analysis of type annotations for Sphinx API documentation in https://github.com/lsst-sqre/documenteer/issues/25#issuecomment-572264101

            Basically, the technology is not quite ready to adopt this toolchain yet.

            Show
            jsick Jonathan Sick added a comment - I added some analysis of type annotations for Sphinx API documentation in https://github.com/lsst-sqre/documenteer/issues/25#issuecomment-572264101 Basically, the technology is not quite ready to adopt this toolchain yet.

              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