[FEATURE] Typer python API docs

[FaustinCarter]

The Typer documentation is, in general, pretty great. But often what I really need is a concise API documentation similar to what Click offers.

If this exists please comment with the link and close the issue, but I feel like I've scoured the existing docs to no avail...

Such documentation would be a lot more straightforward than going to GitHub to read the code directly.

[rth]

but I feel like I've scoured the existing docs to no avail...

Same here. There is no way to see what parameters are supported by typer.Argument in the documentation, short of searching the code on Github. And even there there are no docstring / documentation for parameters.

[laserson]

+1 on this

[mquasar]

I also missed this when reading the docs

[elucify]

At least this issue was here to inform me that what I assumed must exist, doesn't.

I like the idea of seeing the documentation in vscode, but it doesn't show up for me there. 😞

[jaskij]

For me this is a blocker to using Typer in any real capacity.

[MrMino]

Worse yet, many nooks and crannies of the API aren't documented at all. I have a hard time figuring out what many kwargs to Option / Argument mean, and the only way to deal with this right now is reading the code.

[MrMino]

This website introduces the right ideas for this discussion: https://documentation.divio.com/

What Typer lacks is an API reference. The guide docs are cool for newcomers, but in most places the API is symmetrical enough for the more experienced people to not need it at all. What we need is a separate description for each function, method, and class, with their arguments listed and described as well.

[mquasar]

This website introduces the right ideas for this discussion: https://documentation.divio.com/

What Typer lacks is an API reference. The guide docs are cool for newcomers, but in most places the API is symmetrical enough for the more experienced people to not need it at all. What we need is a separate description for each function, method, and class, with their arguments listed and described as well.

This is what I missed the most when I used Typer for a personal project.

[poleguy]

I've used typer happily for several years, and just now realized I can't find any formal documentation for typer.Option() Where can I even get a list of parameters for Option()?

[mjperrone]

This project appears to be built on top of and in relation to click, with more modern python type hints at the core of the interface. Additionally, the existing documentation links to click to explain typer's behavior.

For these reasons, I think think it might be appropriate to set the documentation bar for typer at click's height. Click has a full API reference documentation.

I agree with other commenters here that the documentation would be much appreciated and useful. I think it will be necessary for me be able to convince my coworkers to use typer instead of click for our next python CLI.

[jamesowers-cohere]

Just a plus one that this would be much appreciated - I was searching through the lovely docs for an API reference for typer.Typer, but to no avail! I would have thought that autogenerating these and adding to the docs would be fairly easy, I'll give a PR a crack if I can find time.

Whilst I can see, in my case, the Typer class is not documented, it would still be useful to see what arguments and methods were available at a glance in the lovely docs.

[MrMino]

@tiangolo I'd like to push this an inch forward just by homing in on what's worth documenting in the library and how to do it. Is the following list something that you'd consider ~complete-adjacent?

Things to document:

• typer.Typer class with all of its __init__ arguments.
• The fact that typer.Typer.__call__ is there, what it is for.
• typer.Typer.command args + example(s)
• typer.Typer.callback args + example(s)
• typer.Typer.add_typer() args + example(s)
• typer.Option args + example(s)
• typer.Argument args + example(s)

I'm probably missing a lot of stuff but these seem to be the most used parts.

We would also need to figure out how to make such reference maintainable. I propose adding the docstrings (close to the code) and using something like https://github.com/mkdocstrings/mkdocstrings. The API reference would sit in a separate page.

@tiangolo do we have your blessing?