Support PEP 484 type hints

[nicoonoclaste]

Expected Behavior

When generating doc for a package that is annotated with PEP 484 type hints, I would expect the type hints to be present in the documentation.

For example, the following definition

def foo(x: Bar, repeat : int = 1):
    """Foo-cate a Bar a number of times (default: 1)."""
    ...

results in the type hints being available in the REPL's help():

>>> help(foo)
foo(x: __main__.Bar, repeat: int = 1)
    Foo-cate a Bar a number of times (default: 1).

and it should well as be present in the pdoc-generated documents:

$ pdoc example.py
Module example
==============

Functions
---------

`foo(x: Bar, repeat: int = 1)`
:   Foo-cate a Bar a number of times (default: 1).

Classes
-------

`Bar`

Actual Behavior

pdoc ignores the type-hints:

$ pdoc example.py
Module example
==============

Functions
---------

`foo(x, repeat=1)`
:   Foo-cate a Bar a number of times (default: 1).

Classes
-------

`Bar`

Type hints document the expected types of parameters and return values. As such, they convey a lot of information for the documentation's user, when present.

See PEP 484 for a discussion of type hints.

Steps to Reproduce

Generate documentation for a module that uses type hints

Additional info

• pdoc version: 0.5.1
• Python version: 3.7.2 (default, Jan 3 2019, 02:55:40)

[kernc]

Would you be interested in doing a pull request for that?

You would need to

• add a new method pdoc.Function.annotations() (likened to pdoc.Function.params(), likely simpler) better, and
• modify HTML template to (conditionally) show type annotations.

[nicoonoclaste]

@kernc Sorry, I had entirely missed you replied here. Yes, obviously I'm pretty interested in writing the code for this ^.^

[omtinez]

@nbraud do you plan on submitting a PR with your commit?

[kernc]

@omtinez PR #7 is in progress. Welcome to continue where it's left off.

[kernc]

This is not done. Text template doesn't look into config.mako nor does it print types by default. I'll see what I can do about that and about hyperlinking documented types in HTML output.

[kernc]

Hyperlinked types testable with:

pdoc --html -c show_type_annotations=True your_module

[DaniGuardiola]

Types are not showing up on my project. Fresh pdoc3 install so I assume it is the latest version published, testing it with --http option. Am I missing something? Thanks :)

Edit: didn't read the previous comment. Adding -c show_type_annotations=True worked. I didn't find anything about this option in the documentation though. Also I think the CLI option could be nicer, something like --types / -t.

[DaniGuardiola]

After some more testing I've seen it works pretty well, nice!

I have a couple of suggestions:

• Class / instance property and variable types are not being documented.
• Standard library types could be linked to the official online documentation, specially the Typings library.

[kernc]

@DaniGuardiola, care to open a new issue for missing variable/property annotations?